✨ feat: support the :option: role for CLI arguments - #346
Merged
Conversation
Linking to a flag required the :ref: role with a hand-assembled anchor (`tox-run---magic`), and mixed-case names also forced :force_refs_lower: on. Sphinx resolves the :option: role through a separate `progoptions` table keyed on program and option name, which the directive did not fill. Each rendered flag and positional now also goes through `StandardDomain.add_program_option`, under the same anchor id the :ref: labels use, so `:option:`tox run --magic`` and a `.. program::` scope both resolve without changing any existing URL. Resolves tox-dev#345.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linking to a rendered flag required the
:ref:role with a hand-assembled anchor such as:ref:`tox-run---magic`, and a program or flag with a capital letter also needed:force_refs_lower:. Sphinx resolves the:option:role through its ownprogoptionstable, keyed on program and option name, which the directive did not fill; #345 asks for this.Each flag and positional argument now also registers with
StandardDomain.add_program_option, using the same anchor id the:ref:labels already point at.:option:`tox run --magic`resolves, and so does a bare:option:`--magic`under a.. program:: tox runscope, including the--magic=valuespelling Sphinx strips before lookup. 🔗Existing URLs and
:ref:targets stay as they were. Two limits remain.progoptionsis keyed by program rather than document, sosphinx_argparse_cli_prefix_documentdoes not apply and the first document rendering a program wins. Sphinx only strips=valuewhen the program comes from.. program::, so:option:`tox --magic=1`stays unresolved. The README covers both.