docs: generate reference docs automatically

This is performed with the help of sphinx-click:
https://sphinx-click.readthedocs.io

docs/Makefile

@@ -8,4 +8,4 @@ browse:
 	sensible-browser _build/html/index.html
 
 watch: html browse
-	while true; do inotifywait -e modify *.rst */*.rst ../*.rst conf.py; $(MAKE) html; done
+	while true; do inotifywait -e modify *.rst */*.rst */*/*.rst ../*.rst conf.py; $(MAKE) html; done

docs/conf.py

@@ -1,5 +1,6 @@
 import io
 import os
+import sys
 
 import docutils
 import docutils.parsers.rst
@@ -25,6 +26,13 @@ language = None
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 pygments_style = None
 
+# -- Sphinx-Click configuration
+# https://sphinx-click.readthedocs.io/
+extensions.append('sphinx_click')
+# This is to avoid the addition of the local username to the docs
+os.environ["HOME"] = "~"
+# Make sure that sphinx-click can find the tutor module
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = "sphinx_rtd_theme"

docs/index.rst

@@ -23,6 +23,7 @@
    run
    configuration
    plugins
+   reference
    tutorials
    troubleshooting
    tutor

docs/reference.rst

@@ -0,0 +1,13 @@
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/cli/tutor
+   reference/cli/config
+   reference/cli/dev
+   reference/cli/images
+   reference/cli/k8s
+   reference/cli/local
+   reference/cli/plugins

docs/reference/cli/config.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.config:config_command
+   :prog: tutor config
+   :nested: full

docs/reference/cli/dev.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.dev:dev
+   :prog: tutor dev
+   :nested: full

docs/reference/cli/images.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.images:images_command
+   :prog: tutor images
+   :nested: full

docs/reference/cli/k8s.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.local:local
+   :prog: tutor local
+   :nested: full

docs/reference/cli/local.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.k8s:k8s
+   :prog: tutor k8s
+   :nested: full

docs/reference/cli/plugins.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.plugins:plugins_command
+   :prog: tutor plugins
+   :nested: full

docs/reference/cli/tutor.rst

@@ -0,0 +1,3 @@
+.. click:: tutor.commands.cli:cli
+   :prog: tutor
+   :nested: full

requirements/base.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with python 3.8
+# This file is autogenerated by pip-compile with python 3.7
 # To update, run:
 #
 #    pip-compile requirements/base.in
@@ -20,6 +20,8 @@ google-auth==2.1.0
     # via kubernetes
 idna==3.2
     # via requests
+importlib-metadata==4.8.1
+    # via click
 jinja2==3.0.1
     # via -r requirements/base.in
 kubernetes==18.20.0
@@ -60,14 +62,20 @@ six==1.16.0
     #   python-dateutil
 toml==0.10.2
     # via mypy
-typing-extensions==3.10.0.2
+typed-ast==1.4.3
     # via mypy
+typing-extensions==3.10.0.2
+    # via
+    #   importlib-metadata
+    #   mypy
 urllib3==1.26.7
     # via
     #   kubernetes
     #   requests
 websocket-client==1.2.1
     # via kubernetes
+zipp==3.6.0
+    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools

requirements/dev.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with python 3.8
+# This file is autogenerated by pip-compile with python 3.7
 # To update, run:
 #
 #    pip-compile requirements/dev.in
@@ -50,7 +50,11 @@ idna==3.2
     #   requests
 importlib-metadata==4.8.1
     # via
+    #   -r requirements/base.txt
+    #   click
     #   keyring
+    #   pep517
+    #   pyinstaller
     #   twine
 isort==5.9.3
     # via pylint
@@ -173,6 +177,12 @@ tqdm==4.62.3
     # via twine
 twine==3.4.2
     # via -r requirements/dev.in
+typed-ast==1.4.3
+    # via
+    #   -r requirements/base.txt
+    #   astroid
+    #   black
+    #   mypy
 types-pyyaml==5.4.10
     # via -r requirements/dev.in
 types-setuptools==57.4.0
@@ -182,6 +192,7 @@ typing-extensions==3.10.0.2
     #   -r requirements/base.txt
     #   astroid
     #   black
+    #   importlib-metadata
     #   mypy
     #   pylint
 urllib3==1.26.7
@@ -199,8 +210,11 @@ wheel==0.37.0
     # via pip-tools
 wrapt==1.12.1
     # via astroid
-zipp==3.5.0
-    # via importlib-metadata
+zipp==3.6.0
+    # via
+    #   -r requirements/base.txt
+    #   importlib-metadata
+    #   pep517
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

requirements/docs.in

@@ -1,3 +1,4 @@
 -r base.txt
 sphinx
 sphinx-rtd-theme
+sphinx-click

requirements/docs.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with python 3.8
+# This file is autogenerated by pip-compile with python 3.7
 # To update, run:
 #
 #    pip-compile requirements/docs.in
@@ -24,10 +24,13 @@ charset-normalizer==2.0.6
     #   -r requirements/base.txt
     #   requests
 click==8.0.1
-    # via -r requirements/base.txt
+    # via
+    #   -r requirements/base.txt
+    #   sphinx-click
 docutils==0.17.1
     # via
     #   sphinx
+    #   sphinx-click
     #   sphinx-rtd-theme
 google-auth==2.1.0
     # via
@@ -39,6 +42,10 @@ idna==3.2
     #   requests
 imagesize==1.2.0
     # via sphinx
+importlib-metadata==4.8.1
+    # via
+    #   -r requirements/base.txt
+    #   click
 jinja2==3.0.1
     # via
     #   -r requirements/base.txt
@@ -110,7 +117,10 @@ snowballstemmer==2.1.0
 sphinx==4.2.0
     # via
     #   -r requirements/docs.in
+    #   sphinx-click
     #   sphinx-rtd-theme
+sphinx-click==3.0.1
+    # via -r requirements/docs.in
 sphinx-rtd-theme==1.0.0
     # via -r requirements/docs.in
 sphinxcontrib-applehelp==1.0.2
@@ -129,9 +139,14 @@ toml==0.10.2
     # via
     #   -r requirements/base.txt
     #   mypy
+typed-ast==1.4.3
+    # via
+    #   -r requirements/base.txt
+    #   mypy
 typing-extensions==3.10.0.2
     # via
     #   -r requirements/base.txt
+    #   importlib-metadata
     #   mypy
 urllib3==1.26.7
     # via
@@ -142,6 +157,10 @@ websocket-client==1.2.1
     # via
     #   -r requirements/base.txt
     #   kubernetes
+zipp==3.6.0
+    # via
+    #   -r requirements/base.txt
+    #   importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools