Re: [Django] #36329: Remove non-code custom link text when cross-referencing Python objects in docs

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted

Comment:

Thank you Clifford for this work. I have reviewed some of the examples,
particularly those changed in the PR, and I have mixed feelings about the
need to do any change. I do understand that the method/classes "links" are
formatted as monospaced code-like text, but OTOH the resulting "links"
read/flow nicely in the paragraphs.

Concretely, I am happy to accept the ticket and review the PR in detail.
However, I would appreciate it if you could expand a bit on the motivation
for this change, particularly the broader reasoning or philosophy behind
it.
--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:3>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Clifford Gama):

* Attachment "screen01.jpg" added.

--
Ticket URL: <https://code.djangoproject.com/ticket/36329>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Clifford Gama):

* Attachment "screen02.jpg" added.

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Clifford Gama):

Replying to [comment:3 Natalia Bidart]:

Thank you Natalia for the triage!

> I do understand that the method/classes "links" are formatted as
monospaced code-like text

Yes, and they are wrapped in HTML `<code></code>` tags, with
`class="notranslate"` which means that these links which read nicely in
English will not be translated to other Languages using third-party and
browser translators. (Here is an example using the dev version of the docs
and translating the page with Google Translate to Japanese
[[Image(https://code.djangoproject.com/attachment/ticket/36329/screen01.jpg)]].
And here is how it looks in my PR docs build:
[[Image(https://code.djangoproject.com/attachment/ticket/36329/screen02.jpg)]])

> I would appreciate it if you could expand a bit on the motivation for
this change, particularly the broader reasoning or philosophy behind it.

Using custom link text like “a get lookup” styled as code gives the
impression that “a get lookup” is a literal symbol, which it isn’t. I find
this misleading, especially in longer pages where a reader might skim the
code-formatted terms for quick context. In short, I believe that what
looks like code should be code.

Sphinx documentation does not say anything about what should be used as
custom text in a cross-reference to code. However, I have found that some
projects like matplotlib actively avoid using non-code custom-links to
cross-ref target code. (I have included a regex in the PR description
which you can use to search.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:4>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by David Bogar):

* stage: Accepted => Ready for checkin

Comment:

I agree with Clifford.

This may only be a subjective cosmetic change for people looking at the
page in English, but if it improves accessibility for people who are
having the page translated, then I'm all for it.
--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:5>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Bruno Alla):

* needs_better_patch: 0 => 1
* stage: Ready for checkin => Accepted

Comment:

Spotted a few small issues with the formatting while reviewing.
--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:6>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Clifford Gama):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:7>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:8>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Clifford Gama):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:9>

[Django]

#36329: Remove non-code custom link text when cross-referencing Python objects in
docs
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36329#comment:10>