diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 2e402d7e35..7c5c79f81f 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -1777,7 +1777,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```, + 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..33a3481b67 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -942,11 +942,20 @@ def _resolve_option_xref(self, env: "BuildEnvironment", fromdocname: str, node: pending_xref, contnode: Element) -> Optional[Element]: progname = node.get('std:program') target = target.strip() - docname, labelid = self.progoptions.get((progname, target), ('', '')) + needles = [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), ('', '')) + idx = target.find('=') + if idx != -1: + needles.append(target[:idx]) + # for :option:`-foo[=bar]` search for -foo option directive + idx = target.find('[=') + if idx != -1: + needles.append(target[:idx]) + for needle in needles: + docname, labelid = self.progoptions.get((progname, needle), ('', '')) + 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')