Use 'nested_parse_with_titles'

This allows us to embed titles into our docstrings and have them render
at the correct level.

A test is added, though since this is only testing the formatter it not
a great one. We'll have to integrate 'sphinx.testing' in the future.

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

Author: stephenfin

docs/usage.rst

@@ -77,7 +77,6 @@ module:
         """Greet the world."""
         click.echo('Hello world!')
 
-
 To document this, use the following:
 
 .. code-block:: rst

sphinx_click/ext.py

@@ -5,6 +5,7 @@
 from docutils.parsers import rst
 from docutils.parsers.rst import directives
 from sphinx.util import logging
+from sphinx.util import nodes as sphinx_nodes
 
 LOG = logging.getLogger(__name__)
 CLICK_VERSION = tuple(int(x) for x in click.__version__.split('.')[0:2])
@@ -389,7 +390,7 @@ def _generate_nodes(
             LOG.debug(line)
             result.append(line, source_name)
 
-        self.state.nested_parse(result, 0, section)
+        sphinx_nodes.nested_parse_with_titles(self.state, result, section)
 
         # Subcommands
 

tests/test_formatter.py

@@ -167,6 +167,52 @@ def foobar():
 
         self.assertEqual('', '\n'.join(output))
 
+    def test_titles(self):
+        """Validate a `click.Command` with nested titles."""
+
+        @click.command()
+        @click.option('--name', help='Name to say hello to.', required=True, type=str)
+        def hello(name):
+            """Prints hello to name given.
+
+            Examples
+            --------
+
+            .. code:: bash
+
+                my_cli hello --name "Jack"
+            """
+
+        ctx = click.Context(hello, info_name='hello')
+        output = list(ext._format_command(ctx, show_nested=False))
+
+        self.assertEqual(
+            textwrap.dedent(
+                """
+        Prints hello to name given.
+
+        Examples
+        --------
+
+        .. code:: bash
+
+            my_cli hello --name "Jack"
+
+        .. program:: hello
+        .. code-block:: shell
+
+            hello [OPTIONS]
+
+        .. rubric:: Options
+
+        .. option:: --name <name>
+
+            Name to say hello to.  [required]
+        """
+            ).lstrip(),
+            '\n'.join(output),
+        )
+
 
 class GroupTestCase(unittest.TestCase):
     def test_no_parameters(self):