Merge pull request #9138 from tk0miya/9137_program_None

Add doc and testcase for program directive (refs: #9137)

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).
 

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"