diff options
author | Stephen Finucane <sfinucan@redhat.com> | 2017-06-08 11:53:47 +0100 |
---|---|---|
committer | Stephen Finucane <sfinucan@redhat.com> | 2017-06-08 12:00:23 +0100 |
commit | 632b12a3f7a60b4af1d28639633358671a976123 (patch) | |
tree | 8a5f8b3da6f16ce02cb6fb030686097ea5fc27ed /cliff | |
parent | 2e27ef0e38a7820ffb4221c34749800c7b45852e (diff) | |
download | cliff-632b12a3f7a60b4af1d28639633358671a976123.tar.gz |
sphinext: Use metavar where possible
The Sphinx 'option' directive only allows optional parameter arguments
to be surrounded by brackets - not positional arguments. As a result,
'cliff.sphinxext' will ignore 'action.metavar' for positional arguments
due to the proclivity of said metavars to include surrounding brackets.
However, 'action.metavar' is sometimes important like, for example, when
'action.metavar' is a singular form but 'action.dest' is a plural form.
This can prove very confusing to users.
Start using 'action.metavar' by stripping out these brackets when they
occur. This ensures we get a pretty good approximation of the intent
without breaking Sphinx.
Change-Id: I114fe551f2a249faa49b419e18a99228627a8e83
Diffstat (limited to 'cliff')
-rw-r--r-- | cliff/sphinxext.py | 9 | ||||
-rw-r--r-- | cliff/tests/test_sphinxext.py | 18 |
2 files changed, 23 insertions, 4 deletions
diff --git a/cliff/sphinxext.py b/cliff/sphinxext.py index 7312b42..94fe0e3 100644 --- a/cliff/sphinxext.py +++ b/cliff/sphinxext.py @@ -91,10 +91,11 @@ def _format_positional_action(action): if action.help == argparse.SUPPRESS: return - # NOTE(stephenfin): We use 'dest' - not 'metavar' - because the 'option' - # directive dictates that only option argument names should be surrounded - # by angle brackets - yield '.. option:: {}'.format(action.dest) + # NOTE(stephenfin): We strip all types of brackets from 'metavar' because + # the 'option' directive dictates that only option argument names should be + # surrounded by angle brackets + yield '.. option:: {}'.format( + (action.metavar or action.dest).strip('<>[]() ')) if action.help: yield '' for line in statemachine.string2lines( diff --git a/cliff/tests/test_sphinxext.py b/cliff/tests/test_sphinxext.py index 288149b..9539818 100644 --- a/cliff/tests/test_sphinxext.py +++ b/cliff/tests/test_sphinxext.py @@ -128,6 +128,24 @@ class TestSphinxExtension(base.TestBase): user name """).lstrip(), output) + def test_metavar(self): + """Handle an option with a metavar.""" + parser = argparse.ArgumentParser(prog='hello-world', add_help=False) + parser.add_argument('names', metavar='<NAME>', nargs='+', + help='a user name') + + output = '\n'.join(sphinxext._format_parser(parser)) + self.assertEqual(textwrap.dedent(""" + .. program:: hello-world + .. code-block:: shell + + hello-world <NAME> [<NAME> ...] + + .. option:: NAME + + a user name + """).lstrip(), output) + def test_multiple_opts(self): """Correctly output multiple opts on separate lines.""" parser = argparse.ArgumentParser(prog='hello-world', add_help=False) |