diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 68cab115c9..19fef535c7 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 not (program, name) 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' + '' in content + + @pytest.mark.sphinx('html', testroot='theming') def test_theme_options(app, status, warning): app.build()