Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#31029 closed Cleanup/optimization (fixed)

Link to more specific sections when using the :rfc: role.

Reported by: Baptiste Mispelon Owned by: Baptiste Mispelon
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

While looking at the documentation for the r format of the |date template filter [1], I ended up following the link to the RFC and had to look around the page to find the section that was actually relevant.

It turns out that sphinx's :ref: role supports linking to a specific section of an RFC (this feature is already used in a few places in Django's docs).
I think it would be useful to use that when possible and/or relevant.

So I did some grepping (using git grep -E ':rfc:\`[0-9]+\`') and for each match I tried to see if there was a specific section that was relevant to the context.
I skipped the release notes to save myself some work and because all the matches there were for unsupported versions anyway (10 matches with the latest one for the 1.10 release).

I also added a paragraph in the contributing guide so that other contributors might know about the feature too.

[1] https://docs.djangoproject.com/en/dev/ref/templates/builtins/#date

Change History (10)

comment:1 by Baptiste Mispelon, 5 years ago

comment:2 by Mariusz Felisiak, 5 years ago

Owner: changed from nobody to Baptiste Mispelon
Status: newassigned
Summary: Link to more specific sections when using the `:rfc:` roleLink to more specific sections when using the :rfc: role.
Triage Stage: UnreviewedAccepted

comment:3 by Mariusz Felisiak, 5 years ago

Patch needs improvement: set

comment:4 by Baptiste Mispelon, 5 years ago

Patch needs improvement: unset

comment:5 by Baptiste Mispelon <bmispelon@…>, 5 years ago

In 42df1b1:

Refs #31029 -- Added note about :rfc: role in writing documentation docs.

comment:6 by Baptiste Mispelon <bmispelon@…>, 5 years ago

Resolution: fixed
Status: assignedclosed

In ff1b19d:

Fixed #31029 -- Used more specific links to RFCs.

comment:7 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In c0fe08d4:

[3.0.x] Refs #31029 -- Added note about :rfc: role in writing documentation docs.

Backport of 42df1b178b22d499986516b5d3d6bb70c044901a from master

comment:8 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In 81ddf4b1:

[3.0.x] Fixed #31029 -- Used more specific links to RFCs.

Backport of ff1b19da6761217ed1b14cc7e94c6438903565d8 from master

comment:9 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In 57f5a7e3:

[2.2.x] Refs #31029 -- Added note about :rfc: role in writing documentation docs.

Backport of 42df1b178b22d499986516b5d3d6bb70c044901a from master

comment:10 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In 019a1b9:

[2.2.x] Fixed #31029 -- Used more specific links to RFCs.

Backport of ff1b19da6761217ed1b14cc7e94c6438903565d8 from master

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