Repository navigation
Use roles :data: and :const: for module-level variables and constants #106892
Description
Role :data: is purposed for marking a module-level variable. [1] But role :attr: is often used instead in cases like sys.modules. While technically any module-level variable is accessible as an attribute, I think that it would be better to use more special role :data:.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#role-py-data
Activity
[-]Use role :data: for module-level variables[/-][+]Use roles :data: and :const: for module-level variables and constants[/+]pythongh-106892: Use roles :data: and :const: for referencing module …
pythongh-106892: Use roles :data: and :const: for referencing module …
erlend-aasland commentedon Jul 20, 2023
I agree that
:data:is better than:attr:. Why not:py:data:?serhiy-storchaka commentedon Jul 20, 2023
Because it is the default domain. It can make some sense in the C API documentation to distinguish with the C domain (which is not default), but in the rest of documentation we do not add the
py:prefix.erlend-aasland commentedon Jul 20, 2023
Yes, I know that this was the general guideline before, and I'm fine with using the default (py) domain. I saw some discussion about this recently, but I cannot find it. Perhaps @CAM-Gerlach or @hugovk remembers?
hugovk commentedon Jul 21, 2023
Nope, I don't recall...
gh-106892: Use roles :data: and :const: for referencing module variab…
[3.12] pythongh-106892: Use roles :data: and :const: for referencing …
[3.11] pythongh-106892: Use roles :data: and :const: for referencing …
[3.11] gh-106892: Use roles :data: and :const: for referencing module…
[3.12] gh-106892: Use roles :data: and :const: for referencing module…