Add support for shell-completion

Author: jimporter

CHANGES.md

@@ -2,8 +2,10 @@
 
 ## v1.1.0 (in progress)
 
+### New features
 - Add support for [`!ENV`][mkdocs-env] and [`INHERIT`][mkdocs-inherit] in
   `mkdocs.yml`
+- Add `mike dump-completion` to generate shell-completion functions
 
 [mkdocs-env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
 [mkdocs-inherit]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance

README.md

@@ -39,6 +39,12 @@ is what you might expect:
 pip install mike
 ```
 
+Once you've installed mike, you might also want to set up shell-completion for
+it. If you have [shtab][shtab] installed, you can do this with
+`mike dump-completion`, which will print the shell-completion code for your
+shell. For more details on how to set this up, consult shtab's
+[documentation][shtab-setup].
+
 ## Usage
 
 ### Initialization
@@ -261,4 +267,6 @@ This project is licensed under the [BSD 3-clause license](LICENSE).
 [bfg9000]: https://jimporter.github.io/bfg9000
 [material-insiders]: https://squidfunk.github.io/mkdocs-material/insiders/
 [setuptools]: https://pythonhosted.org/setuptools/
+[shtab]: https://github.com/iterative/shtab
+[shtab-setup]: https://github.com/iterative/shtab#cli-usage
 [jinja]: https://jinja.palletsprojects.com/

mike/driver.py

@@ -1,4 +1,5 @@
 import argparse
+import os
 import sys
 
 from . import commands
@@ -49,6 +50,10 @@
 Start the development server, serving pages from the target branch.
 """
 
+dump_completion_desc = """
+Print shell-completion functions.
+"""
+
 
 def add_git_arguments(parser, *, commit=True, prefix=True):
     # Add this whenever we add git arguments since we pull the remote and
@@ -211,6 +216,15 @@ def help(parser, args):
     parser.parse_args(args.subcommand + ['--help'])
 
 
+def dump_completion(parser, args):
+    try:
+        import shtab
+        print(shtab.complete(parser, shell=args.shell))
+    except ImportError:
+        print('shtab not found; install via `pip install shtab`')
+        return 1
+
+
 def main():
     parser = argparse.ArgumentParser(prog='mike', description=description)
     subparsers = parser.add_subparsers(metavar='COMMAND')
@@ -315,6 +329,16 @@ def main():
     help_p.add_argument('subcommand', metavar='CMD', nargs=argparse.REMAINDER,
                         help='subcommand to request help for')
 
+    completion_p = subparsers.add_parser(
+        'dump-completion', description=dump_completion_desc,
+        help='print shell completion script'
+    )
+    completion_p.set_defaults(func=dump_completion)
+    shell = (os.path.basename(os.environ['SHELL'])
+             if 'SHELL' in os.environ else None)
+    completion_p.add_argument('-s', '--shell', metavar='SHELL', default=shell,
+                              help='shell type (default: %(default)s)')
+
     args = parser.parse_args()
     try:
         return args.func(parser, args)

setup.py

@@ -96,8 +96,8 @@ def distribution_files(self):
 
     install_requires=(['mkdocs >= 1.0', 'jinja2', 'pyyaml >= 5.1', 'verspec']),
     extras_require={
-        'dev': ['coverage', 'flake8 >= 3.0'],
-        'test': ['coverage', 'flake8 >= 3.0'],
+        'dev': ['coverage', 'flake8 >= 3.0', 'shtab'],
+        'test': ['coverage', 'flake8 >= 3.0', 'shtab'],
     },
 
     entry_points={

test/integration/test_help.py renamed to test/integration/test_command_line.py

@@ -17,3 +17,9 @@ def test_help_subcommand(self):
     def test_help_subcommand_extra(self):
         output = assertPopen(['mike', 'help', 'deploy', '--rebase'])
         self.assertRegex(output, r'^usage: mike deploy')
+
+
+class DumpCompletionTest(unittest.TestCase):
+    def test_completion(self):
+        output = assertPopen(['mike', 'dump-completion', '-sbash'])
+        self.assertRegex(output, r'^#!/usr/bin/env bash')