Skip to content

Commit

Permalink
Use 'nested_parse_with_titles'
Browse files Browse the repository at this point in the history
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 <[email protected]>
Closes: #63
  • Loading branch information
stephenfin committed Jul 23, 2020
1 parent 8bfb76a commit f066122
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 2 deletions.
1 change: 0 additions & 1 deletion docs/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,6 @@ module:
"""Greet the world."""
click.echo('Hello world!')
To document this, use the following:

.. code-block:: rst
Expand Down
3 changes: 2 additions & 1 deletion sphinx_click/ext.py
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down Expand Up @@ -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

Expand Down
46 changes: 46 additions & 0 deletions tests/test_formatter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down

0 comments on commit f066122

Please sign in to comment.