Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Disambiguate :type: as a directive option or field-list item #13242

Merged
merged 1 commit into from
Jan 15, 2025

Conversation

AA-Turner
Copy link
Member

@AA-Turner AA-Turner commented Jan 14, 2025

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:

 .. attribute:: TarInfo.mtime
-   :type: int | float
+   :type: int or float

This is because :type: is interepreted as the directive option, which runs through sphinx.domains.python._annotations._parse_annotation() and employs an ast unparser. The correct change would have been:

 .. attribute:: TarInfo.mtime
-   :type: int | float
+
+   :type: int or float

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 with sphinx.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

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

@AA-Turner AA-Turner added this to the 8.2.0 milestone Jan 14, 2025
@AA-Turner AA-Turner merged commit 182c831 into sphinx-doc:master Jan 15, 2025
7 checks passed
@gvanrossum
Copy link

So, int | float is "a valid Python expression" but int or float is not? That seems am odd definition of "Python expression" -- presumably I am missing something? Also this would seem to disallow things like file-like in Sphinx types?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants