DOC add basic example with CommandCollection

docs/conf.py

@@ -15,7 +15,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ["sphinx_click"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []

docs/examples/commandcollections.rst

@@ -0,0 +1,27 @@
+.. _example_commandcollections:
+
+Documentating |CommandCollection|
+=================================
+
+The client in the file ``examples/commandcollections/cli.py`` using a
+|CommandCollection| such as
+
+.. literalinclude:: ../../examples/commandcollections/cli.py
+
+The automatic documentation using *sphinx-click* gives for the following directive:
+
+.. code-block:: rst
+
+   .. click:: commandcollections.cli:cli
+     :prog: cli
+     :nested: full
+
+----
+
+.. click:: commandcollections.cli:cli
+  :prog: cli
+  :nested: full
+
+
+.. |CommandCollection| replace:: ``CommandCollection``
+.. _CommandCollection: https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection

docs/examples/index.rst

@@ -0,0 +1,8 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/index.rst

@@ -15,6 +15,7 @@ __ http://click.pocoo.org/
    usage
    contributing
    changelog
+   examples/index
 
 .. seealso::
 

docs/usage.rst

@@ -147,6 +147,27 @@ the roles provided by the `Sphinx standard domain`_.
 
     __ https://github.com/sphinx-doc/sphinx/issues/880
 
+Documenting |CommandCollection|_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When building more complex CLI, one might need to bring together multiple groups
+of commands and make them accessible using a single client with |CommandCollection|_.
+*sphinx-click* renders collection of commands with multiple sections, one for each
+group listed in the command ``sources``. The group names are used as section titles
+and the help string from the description are used as section description.
+Thus, a client defined using a |CommandCollection| as ``cli`` will be rendered
+using *sphinx-click* and the following directive
+
+.. code-block:: rst
+
+   .. click:: cli:cli
+      :prog: cli
+      :nested: full
+
+with the subcommands of each group in different sections, one for each group in
+``sources``. An example is provided in :ref:`example_commandcollections`.
+
+
 Modifying ``sys.path``
 ----------------------
 
@@ -184,3 +205,6 @@ assuming the group or command in ``git.git`` is named ``cli``.
 
 Refer to `issue #2 <https://github.com/click-contrib/sphinx-click/issues/2>`__
 for more information.
+
+.. |CommandCollection| replace:: :code:`CommandCollection`
+.. _CommandCollection: https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection

examples/commandcollections/cli.py

@@ -0,0 +1,40 @@
+# file: cli.py
+import click
+
+
+main = click.Group(
+    name='Principal Commands',
+    help="Principal commands that are used in ``cli``.\n\n"
+    "The section name and description are obtained using the name and "
+    "description of the group passed as sources for |CommandCollection|_."
+)
+
+
+@main.command(help='CMD 1')
+def cmd1():
+    print('call cmd 1')
+
+
+helpers = click.Group(
+    name='Helper Commands',
+    help="Helper commands for ``cli``."
+)
+
+
+@helpers.command()
+def cmd2():
+    "Helper command that has no option."
+    pass
+
+
+@helpers.command()
+@click.option('--user', type=str)
+def cmd3(user):
+    "Helper command with an option."
+    pass
+
+
+cli = click.CommandCollection(
+    name='cli', sources=[main, helpers],
+    help='Some general info on ``cli``.'
+)

examples/setup.py

@@ -0,0 +1,7 @@
+from setuptools import find_packages, setup
+
+setup(
+    name='sphinx_click_examples',
+    packages=find_packages('.'),
+    install_requires=['click']
+)

tox.ini

@@ -29,6 +29,7 @@ branch = True
 
 [testenv:docs]
 commands =
+    pip install -e {toxinidir}/examples/
     sphinx-build -W -b html -d docs/_build/doctrees docs docs/_build/html
 
 [travis]