Extend cross referencing options with values (#10883)

This change means that text following `=`, `[=`, or ` ` is ignored when
searching for a corresponding option directive to an option cross reference
role. These are commonly used options, for example `--profile=path`, 
`--profile[=path]` or `--profile path`.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

doc/usage/restructuredtext/domains.rst

@@ -1803,7 +1803,8 @@ There is a set of directives allowing documenting command-line programs:
 
    .. versionchanged:: 5.3
 
-      One can cross-reference including an option value: ``:option:`--module=foobar```.
+      One can cross-reference including an option value: ``:option:`--module=foobar```,
+      ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
 
    Use :confval:`option_emphasise_placeholders` for parsing of
    "variable part" of a literal text (similarly to the :rst:role:`samp` role).

sphinx/domains/std.py

@@ -943,10 +943,17 @@ class StandardDomain(Domain):
         progname = node.get('std:program')
         target = target.strip()
         docname, labelid = self.progoptions.get((progname, target), ('', ''))
-        # for :option:`-foo=bar` search for -foo option directive
-        if not docname and '=' in target:
-            target2 = target[:target.find('=')]
-            docname, labelid = self.progoptions.get((progname, target2), ('', ''))
+        if not docname:
+            # Support also reference that contain an option value:
+            # * :option:`-foo=bar`
+            # * :option:`-foo[=bar]`
+            # * :option:`-foo bar`
+            for needle in {'=', '[=', ' '}:
+                if needle in target:
+                    stem, _, _ = target.partition(needle)
+                    docname, labelid = self.progoptions.get((progname, stem), ('', ''))
+                    if docname:
+                        break
         if not docname:
             commands = []
             while ws_re.search(target):

tests/roots/test-root/objects.txt

@@ -214,7 +214,8 @@ Test repeated option directive.
 
   My secret API.
 
-Reference the first option :option:`-mapi=secret`.
+Reference the first option :option:`-mapi=secret`, :option:`-mapi[=xxx]`
+or :option:`-mapi with_space`.
 
 
 User markup

tests/test_build_html.py

@@ -1771,6 +1771,9 @@ def test_option_reference_with_value(app, status, warning):
     assert ('<span class="pre">-mapi</span></span><span class="sig-prename descclassname">'
             '</span><a class="headerlink" href="#cmdoption-git-commit-mapi"') in content
     assert 'first option <a class="reference internal" href="#cmdoption-git-commit-mapi">' in content
+    assert ('<a class="reference internal" href="#cmdoption-git-commit-mapi">'
+            '<code class="xref std std-option docutils literal notranslate"><span class="pre">-mapi[=xxx]</span></code></a>') in content
+    assert '<span class="pre">-mapi</span> <span class="pre">with_space</span>' in content
 
 
 @pytest.mark.sphinx('html', testroot='theming')