extend option directive syntax

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

5 files changed, 36 insertions, 1 deletions

diff --git a/CHANGES b/CHANGES
index d40e86b91..79f6b80e0 100644
--- a/CHANGES
+++ b/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
 ----------
 
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index 397416a89..2e402d7e3 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/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).
 
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index c6a05875f..ef13e156e 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -780,7 +780,9 @@ class StandardDomain(Domain):
             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 @@ 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:
             commands = []
             while ws_re.search(target):
diff --git a/tests/roots/test-root/objects.txt b/tests/roots/test-root/objects.txt
index a4a5c667c..fa9e475e5 100644
--- a/tests/roots/test-root/objects.txt
+++ b/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
 ===========
 
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index 0cdeb4708..453225e18 100644
--- a/tests/test_build_html.py
+++ b/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()