pathlib.PurePath properties annotated with .. data directive

[pganssle]

BPO	42444
Nosy	@ezio-melotti, @merwok, @willingc, @JulienPalard, @pganssle, @ZackerySpytz
PRs	bpo-42444: Use attribute directives in the docs for pathlib.PurePath #24977

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-11-23.15:58:31.527>
labels = ['3.10', 'docs']
title = 'pathlib.PurePath properties annotated with .. data directive'
updated_at = <Date 2021-03-22.17:53:20.182>
user = 'https://github.com/pganssle'

bugs.python.org fields:

activity = <Date 2021-03-22.17:53:20.182>
actor = 'ZackerySpytz'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-11-23.15:58:31.527>
creator = 'p-ganssle'
dependencies = []
files = []
hgrepos = []
issue_num = 42444
keywords = ['patch']
message_count = 1.0
messages = ['381673']
nosy_count = 7.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'docs@python', 'willingc', 'mdk', 'p-ganssle', 'ZackerySpytz']
pr_nums = ['24977']
priority = 'low'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue42444'
versions = ['Python 3.10']

Linked PRs

• gh-86610: Use attribute directive in docs for pathlib.PurePath #101114
• [3.11] gh-86610: Use attribute directive in docs for pathlib.PurePath (GH-101114) #101205
• [3.10] gh-86610: Use attribute directive in docs for pathlib.PurePath (GH-101114) #101206

[pganssle]

Currently, it seems that the pathlib module uses `.. data::` to annotate the properties of the PurePath type (e.g. .parts, .drive, .root, etc). See: https://github.com/python/cpython/blob/ff420f0e08a2443339da0df7ace95e14177bac53/Doc/library/pathlib.rst

According to the documentation (https://devguide.python.org/documenting/#information-units), data is for module-level constants, specifically:

Describes global data in a module, including both variables and values used
as “defined constants.” Class and object attributes are not documented using
this directive.

I believe that we should switch these over to use the `.. attribute:` directive instead.

From what I can tell, you can still link to these attributes using the `:attr:` role. I haven't checked if you can link to `:attribute:`s using the `:data:` role, though. If not, it might break some links to change these to `:attribute:`.

[hauntsaninja]

Thanks for fixing!