diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 65a32b6c8..dfd347327 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -1680,6 +1680,9 @@ There is a set of directives allowing documenting command-line programs: then ``:option:`rm -r``` would refer to the first option, while ``:option:`svn -r``` would refer to the second one. + If ``None`` is passed to the argument, the directive will reset the + current program name. + The program name may contain spaces (in case you want to document subcommands like ``svn add`` and ``svn commit`` separately). diff --git a/tests/test_domain_std.py b/tests/test_domain_std.py index 9d9e27bd0..011c82f6a 100644 --- a/tests/test_domain_std.py +++ b/tests/test_domain_std.py @@ -324,6 +324,23 @@ def test_cmdoption(app): assert domain.progoptions[('ls', '-l')] == ('index', 'cmdoption-ls-l') +def test_cmdoption_for_None(app): + text = (".. program:: ls\n" + ".. program:: None\n" + "\n" + ".. option:: -l\n") + domain = app.env.get_domain('std') + doctree = restructuredtext.parse(app, text) + assert_node(doctree, (addnodes.index, + [desc, ([desc_signature, ([desc_name, "-l"], + [desc_addname, ()])], + [desc_content, ()])])) + assert_node(doctree[0], addnodes.index, + entries=[('pair', 'command line option; -l', 'cmdoption-l', '', None)]) + assert (None, '-l') in domain.progoptions + assert domain.progoptions[(None, '-l')] == ('index', 'cmdoption-l') + + def test_multiple_cmdoptions(app): text = (".. program:: cmd\n" "\n"