Standardize usage of single backticks for variables in docstrings.

[tlambert03]

📚 Documentation

as pointed out by @Carreau in #2279 (comment), there are plenty of places in our docstrings where double backticks are being used stylistically, to achieve <pre> styling in the sphinxdocs... but this conflates style with semantics. This has been discussed a lot elsewhere (see e.g. sympy/sympy#13519 and SO).

The truth is, the meaning of a single back-tick in rst is a little vague, these docs call single backticks "interpreted text" and note:

The rendering and meaning of interpreted text is domain- or application-dependent. It can be used for things like index entries or explicit descriptive markup (like program identifiers).

So... it really is "what we make of it." ... but the numpy docstring guide says:

Enclose variables in single backticks.

so that's good enough for me! (I'm probably the biggest offender here in terms of using double backticks to get the desired sphinx style)

Sphinx uses <cite>content</cite> for single backticks and <em>content</em> for asterisks, and while the default rendering of <cite> appears to be italicizes, we can change that on the CSS side.

So, fixing this will require going through the docstrings and replacing variables in double backticks with single backticks. note, numpy docs say "For inline display use double backticks (like y = np.sin(x))."... so double backticks aren't always unacceptable, but shouldn't be used for variable names.

rst docs say double backticks are "inline literals" which are "Normally rendered as monospaced text. Spaces should be preserved, but line breaks will not be."

@kne42

[Carreau]

Thanks @tlambert03, I think internally in sphinx single backticks will be converted to a inline directive with a role and name, it just happened that if there is None, sphinx try to "guess", and the "guess" is part of sphinx configuration.

I don't think this is critical in the short term, and likely something I can try to address in vélin. Maybe this is something we can also talk about with the Jupyter Book crowed as well. I know the single-vs double is also quite confusing comming from markdown.

[jni]

Thanks @tlambert03, I think internally in sphinx single backticks will be converted to a inline directive with a role and name, it just happened that if there is None, sphinx try to "guess", and the "guess" is part of sphinx configuration.

Yeah, so I've started using :py:func:`my_function` when I want a function specifically, but what is the directive for a function parameter, @Carreau? "in the face of ambiguity, refuse the temptation to guess". ;)

[tlambert03]

I don't think there is one. The :func:my_function: role actually links to a reference in the Sphinx index, but parameters don't have such cross-reference indices... hence the confusion here

[jni]

That's... annoying. LOL

[sofroniewn]

Thanks for raising this @tlambert03, I'll go with to whatever the recommended best practices here are

[Carreau]

Personally I think that staying with single in the codebase and working on fixing the styling/directive-role in sphinx is the right way to go.

It may be a matter of updating numpydoc to emit references in parameters.