docs: Use backticks as literal in Sphinx

[wenzeslaus]

Set the default role in Sphinx to literal so that backticks (not just double backticks) are interpreted as literal. Now they are interpreted as text in emphasis, but literal aligns that to Markdown use of backticks.

Background

While backticks mean a different thing in Sphinx/reStructuredText and Markdown, Sphinx can be configured to produce the same thing as a typical Markdown rendering, using the default role. While in another world, having the default role as py:obj or any would be an interesting option, with all the Markdown around us, having backticks interpreted as literal or code is most advantageous because it removes the issues when switching between Sphinx with reStructuredText for Python and Markdown everywhere else (Doxygen also supports Markdown).

My motivation for this is that @echoix pointed out in #6366 that I may be wrongly assuming what backticks actually do in Python documentation.

Before

After

The result is aligned with how Python documentation displays things, at least that's what I was trying to mimic with asterisk (italics) and backticks (monospace) parts.

[echoix]

Is there some current docstrings that need to be fixed following this change? Are the currently "fixed" double backticks still valid?

[wenzeslaus]

Good questions.

Are the currently "fixed" double backticks still valid?

The double backticks is unrelated to this in a sense that this changes how single backticks is interpreted (it changes the default role of it). Explicit roles before single backticks are not affected either. In other words, this is about roles, not about monospace/verbatim text. ...just learned that now.

Is there some current docstrings that need to be fixed following this change?

As for the current code, my assumption is that if any current code is using single backticks now, it indeed meant to use it for some sort of monospace code rendering, so this is correcting it.

The unset default role resulted in emphasis/italics. That would be appropriate for things like functions or objects. If describing an object was the intention of using single backticks (but explicit role py:obj was omitted), monospace will not be a big mistake...it is still a code and it is still not linked anywhere.

The following search shows plenty of places with majority being in the first category (monospace) and minority in the second (could link to functions).

grep -IrnE "[^\`:]\`[^\`]+\`[^\`]"

[petrasovaa]

I will approve this and the places that need to be fixed can go into separate PR.