Disambiguate :type:
as a directive option or field-list item
#13242
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.
Purpose
It is currently very confusing. We should make it less so.
Notably, @erlend-aasland's change failed to create a cross-reference, with the following rST:
This is because
:type:
is interepreted as the directive option, which runs throughsphinx.domains.python._annotations._parse_annotation()
and employs anast
unparser. The correct change would have been:The extra blank line seperates directive arguments and options from their content. In this context,
:type:
becomes a field list entry, which is then parsed withsphinx.domains.python._object.PyXrefMixin._delimiters_re
, a regular expression that includes the ability to split on'or'
.Note that I'm not suggesting that any of this makes sense, but at least we can improve the documentation as a first step...
References
d464f3f
(#116389)Preview
https://sphinx--13242.org.readthedocs.build/en/13242/usage/domains/python.html#directive-option-py-attribute-type
https://sphinx--13242.org.readthedocs.build/en/13242/usage/domains/python.html#info-field-lists
cc @erlend-aasland @nedbat
A