extend option directive syntax

One can cross-reference an option value: :option:`--module=foobar`.

Author: marxin

CHANGES

@@ -13,6 +13,9 @@ Deprecated
 Features added
 --------------
 
+* #10840: One can cross-reference including an option value: ``:option:`--module=foobar```.
+  Patch by Martin Liska.
+
 Bugs fixed
 ----------
 

doc/usage/restructuredtext/domains.rst

@@ -1775,6 +1775,10 @@ There is a set of directives allowing documenting command-line programs:
    referenceable by :rst:role:`option` (in the example case, you'd use something
    like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
 
+   .. versionchanged:: 5.3
+
+      One can cross-reference including an option value: ``: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

@@ -780,7 +780,9 @@ def process_doc(self, env: "BuildEnvironment", docname: str, document: nodes.doc
             self.labels[name] = docname, labelid, sectname
 
     def add_program_option(self, program: str, name: str, docname: str, labelid: str) -> None:
-        self.progoptions[program, name] = (docname, labelid)
+        # prefer first command option entry
+        if (program, name) not in self.progoptions:
+            self.progoptions[program, name] = (docname, labelid)
 
     def build_reference_node(self, fromdocname: str, builder: "Builder", docname: str,
                              labelid: str, sectname: str, rolename: str, **options: Any
@@ -941,6 +943,10 @@ def _resolve_option_xref(self, env: "BuildEnvironment", fromdocname: str,
         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:
             commands = []
             while ws_re.search(target):

tests/roots/test-root/objects.txt

@@ -204,6 +204,19 @@ Link to :option:`hg commit` and :option:`git commit -p`.
 
 Foo bar.
 
+Test repeated option directive.
+
+.. option:: -mapi
+
+  My API.
+
+.. option:: -mapi=secret
+
+  My secret API.
+
+Reference the first option :option:`-mapi=secret`.
+
+
 User markup
 ===========
 

tests/test_build_html.py

@@ -1764,6 +1764,15 @@ def test_option_emphasise_placeholders_default(app, status, warning):
             '<a class="headerlink" href="#cmdoption-perl-plugin.option" title="Permalink to this definition">¶</a></dt>') in content
 
 
+@pytest.mark.sphinx('html', testroot='root')
+def test_option_reference_with_value(app, status, warning):
+    app.build()
+    content = (app.outdir / 'objects.html').read_text()
+    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
+
+
 @pytest.mark.sphinx('html', testroot='theming')
 def test_theme_options(app, status, warning):
     app.build()