Opened 4 weeks ago

Closed 4 weeks ago

Last modified 4 weeks ago

#36570 closed Cleanup/optimization (fixed)

Remove ":py" domain from roles

Reported by: Tim Graham Owned by: JaeHyuckSa
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

In the documentation source files, there's some confusion about roles like :py:class:`email.message.EmailMessage`. In this case, py indicates the Python language domain (which means any code written in Python, not Python built-ins in particular).

Since the Python domain is the default in Sphinx, you can omit the :py prefix when referring to Python objects, for example, using :class: instead of :py:class:.

Including :py ensures clarity and avoids ambiguity if other domains are also in use., but since the Django documentation doesn't use other domains (C++, JavaScript, etc.), I see no reason to include the prefix.

Change History (8)

comment:1 by JaeHyuckSa, 4 weeks ago

Owner: set to JaeHyuckSa
Status: newassigned

comment:2 by Sarah Boyce, 4 weeks ago

Triage Stage: UnreviewedAccepted

comment:3 by JaeHyuckSa, 4 weeks ago

Has patch: set

comment:4 by Sarah Boyce, 4 weeks ago

Patch needs improvement: set

comment:5 by JaeHyuckSa, 4 weeks ago

Patch needs improvement: unset

comment:6 by Sarah Boyce, 4 weeks ago

Triage Stage: AcceptedReady for checkin

comment:7 by Sarah Boyce <42296566+sarahboyce@…>, 4 weeks ago

Resolution: fixed
Status: assignedclosed

In 3c0c5435:

Fixed #36570 -- Removed unnecessary :py domain from documentation roles.

Signed-off-by: SaJH <wogur981208@…>

comment:8 by Sarah Boyce <42296566+sarahboyce@…>, 4 weeks ago

In 05bac8c4:

Refs #36570 -- Added sphinxlint checker to flag unnecessary :py domain in documentation roles.

Note: See TracTickets for help on using tickets.
Back to Top