IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Extend cross referencing options with values (#10883)

Browse Source 
This change means that text following `=`, `[=`, or ` ` is ignored when
searching for a corresponding option directive to an option cross reference
role. These are commonly used options, for example `--profile=path`, 
`--profile[=path]` or `--profile path`.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Martin Liška 2022-10-02 16:50:53 +02:00 committed by GitHub
parent 7765940f14
commit 0a91adb64d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 18 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/usage/restructuredtext/domains.rst
View File

@ -1803,7 +1803,8 @@ There is a set of directives allowing documenting command-line programs:
.. versionchanged:: 5.3 .. 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 Use :confval:`option_emphasise_placeholders` for parsing of
"variable part" of a literal text (similarly to the :rst:role:`samp` role). "variable part" of a literal text (similarly to the :rst:role:`samp` role).

15
sphinx/domains/std.py
View File

@ -943,10 +943,17 @@ class StandardDomain(Domain):
progname = node.get('std:program') progname = node.get('std:program')
target = target.strip() target = target.strip()
docname, labelid = self.progoptions.get((progname, target), ('', '')) docname, labelid = self.progoptions.get((progname, target), ('', ''))
# for :option:`-foo=bar` search for -foo option directive if not docname:
if not docname and '=' in target: # Support also reference that contain an option value:
target2 = target[:target.find('=')] # * :option:`-foo=bar`
docname, labelid = self.progoptions.get((progname, target2), ('', '')) # * :option:`-foo[=bar]`
# * :option:`-foo bar`
for needle in {'=', '[=', ' '}:
if needle in target:
stem, _, _ = target.partition(needle)
docname, labelid = self.progoptions.get((progname, stem), ('', ''))
if docname:
break
if not docname: if not docname:
commands = [] commands = []
while ws_re.search(target): while ws_re.search(target):

3
tests/roots/test-root/objects.txt
View File

@ -214,7 +214,8 @@ Test repeated option directive.
My secret API. My secret API.
Reference the first option :option:`-mapi=secret`. Reference the first option :option:`-mapi=secret`, :option:`-mapi[=xxx]`
or :option:`-mapi with_space`.
User markup User markup

3
tests/test_build_html.py
View File

@ -1771,6 +1771,9 @@ def test_option_reference_with_value(app, status, warning):
assert ('<span class="pre">-mapi</span></span><span class="sig-prename descclassname">' assert ('<span class="pre">-mapi</span></span><span class="sig-prename descclassname">'
'</span><a class="headerlink" href="#cmdoption-git-commit-mapi"') in content '</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 assert 'first option <a class="reference internal" href="#cmdoption-git-commit-mapi">' in content
assert ('<a class="reference internal" href="#cmdoption-git-commit-mapi">'
'<code class="xref std std-option docutils literal notranslate"><span class="pre">-mapi[=xxx]</span></code></a>') in content
assert '<span class="pre">-mapi</span> <span class="pre">with_space</span>' in content
@pytest.mark.sphinx('html', testroot='theming') @pytest.mark.sphinx('html', testroot='theming')