diff --git a/CHANGES b/CHANGES
index d40e86b912..5aa9cb18d0 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 397416a890..1d0c663dc4 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 c6a05875f0..ef13e156e4 100644
--- a/sphinx/domains/std.py
+++ b/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):
diff --git a/tests/roots/test-root/objects.txt b/tests/roots/test-root/objects.txt
index a4a5c667c9..fa9e475e56 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 0cdeb4708d..453225e18e 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):
'') 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 ('-mapi'
+ '