#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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019642085896-b9b39082-37c7-4329-8f18-2b6b9821de5c-000000%40eu-central-1.amazonses.com.
