docs: Add more examples

Signed-off-by: Stephen Finucane <stephen@that.guru>

docs/examples/commandcollections.rst

@@ -1,5 +1,5 @@
-Documenting |CommandCollection|
-=================================
+Documenting command collections
+===============================
 
 Consider the following sample application, using |CommandCollection|_:
 
@@ -13,12 +13,13 @@ This can be documented using *sphinx-click* like so:
      :prog: cli
      :nested: full
 
+The rendered example is shown below.
+
 ----
 
 .. click:: commandcollections.cli:cli
   :prog: cli
   :nested: full
 
-
 .. |CommandCollection| replace:: ``CommandCollection``
 .. _CommandCollection: https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection

docs/examples/commands.rst

@@ -0,0 +1,25 @@
+Documenting commands
+====================
+
+Consider the following sample application, using |Command|_:
+
+.. literalinclude:: ../../examples/commands/cli.py
+
+This can be documented using *sphinx-click* like so:
+
+.. code-block:: rst
+
+   .. click:: commands.cli:cli
+     :prog: cli
+     :nested: full
+
+The rendered example is shown below.
+
+----
+
+.. click:: commands.cli:cli
+  :prog: cli
+  :nested: full
+
+.. |Command| replace:: ``Command``
+.. _Command: https://click.palletsprojects.com/en/7.x/api/#click.Command

docs/examples/groups.rst

@@ -0,0 +1,25 @@
+Documenting groups
+==================
+
+Consider the following sample application, using |Group|_:
+
+.. literalinclude:: ../../examples/groups/cli.py
+
+This can be documented using *sphinx-click* like so:
+
+.. code-block:: rst
+
+   .. click:: groups.cli:cli
+     :prog: cli
+     :nested: full
+
+The rendered example is shown below.
+
+----
+
+.. click:: groups.cli:cli
+  :prog: cli
+  :nested: full
+
+.. |Group| replace:: ``Groups``
+.. _Group: https://click.palletsprojects.com/en/7.x/api/#click.Group

docs/examples/index.rst

@@ -3,6 +3,7 @@ Examples
 
 .. toctree::
    :maxdepth: 1
-   :glob:
 
-   *
+   commands
+   groups
+   commandcollections

examples/commandcollections/cli.py

@@ -4,9 +4,11 @@
 
 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|_.",
+    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|_."
+    ),
 )
 
 

examples/commands/cli.py

@@ -0,0 +1,27 @@
+# file: cli.py
+import click
+
+
+@click.command()
+@click.option('--param', envvar='PARAM', help='A sample option')
+@click.option('--another', metavar='[FOO]', help='Another option')
+@click.option(
+    '--choice',
+    help='A sample option with choices',
+    type=click.Choice(['Option1', 'Option2']),
+)
+@click.option(
+    '--numeric-choice',
+    metavar='<choice>',
+    help='A sample option with numeric choices',
+    type=click.Choice([1, 2, 3]),
+)
+@click.option(
+    '--flag',
+    is_flag=True,
+    help='A boolean flag',
+)
+@click.argument('ARG', envvar='ARG')
+def cli(bar):
+    """A sample command."""
+    pass

examples/groups/cli.py

@@ -0,0 +1,22 @@
+# file: cli.py
+import click
+
+
+@click.group()
+@click.option(
+    '--debug',
+    default=False,
+    is_flag=True,
+    help="Output more information about what's going on.",
+)
+def cli():
+    """A sample command group."""
+    pass
+
+
+@cli.command()
+@click.option('--param', envvar='PARAM', help='A sample option')
+@click.option('--another', metavar='[FOO]', help='Another option')
+def hello():
+    """A sample command."""
+    pass