diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index f2f07927d4..cc0713b9fd 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/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). diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index ef13e156e4..b629899b40 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -943,10 +943,17 @@ 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: + # Support also reference that contain an option value: + # * :option:`-foo=bar` + # * :option:`-foo[=bar]` + # * :option:`-foo bar` + for needle in ('=', '[=', ' '): + idx = target.find(needle) + if idx != -1: + docname, labelid = self.progoptions.get((progname, target[:idx]), ('', '')) + if docname: + break 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 fa9e475e56..36c8dd051d 100644 --- a/tests/roots/test-root/objects.txt +++ b/tests/roots/test-root/objects.txt @@ -214,7 +214,7 @@ Test repeated option directive. My secret API. -Reference the first option :option:`-mapi=secret`. +Reference the first option :option:`-mapi=secret` or :option:`-mapi[=xxx]`. User markup diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 453225e18e..15c488be48 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -1771,6 +1771,8 @@ def test_option_reference_with_value(app, status, warning): assert ('-mapi' '' in content + assert ('' + '-mapi[=xxx]') in content @pytest.mark.sphinx('html', testroot='theming')