Remove non-code custom link text when cross-referencing Python objects in docs

[Clifford Gama]

Some cross-references to Python objects in the docs use custom link text that isn't actual code, eg :meth:a get lookup <django.models.QuerySet.get> ​here. This is undesirable because it causes natural language phrases like "a get lookup", in this example, to render as inline code.

[Clifford Gama]

​PR

[Natalia Bidart]

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.

[Clifford Gama]

Replying to 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 . And here is how it looks in my PR docs build: )

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.)

[David Bogar]

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.

[Bruno Alla]

Spotted a few small issues with the formatting while reviewing.