Document when to use single backticks

Related to https://github.com/scikit-learn/scikit-learn/pull/13542, https://github.com/scikit-learn/scikit-learn/pull/13542

Currently our single backticks will resolve as follows: python->glossary->code. We should document when we recommend to use single backticks.

@NicolasHug mentioned in https://github.com/scikit-learn/scikit-learn/pull/14381#pullrequestreview-275449342

I’d also still recommend double backticks by default and only use single backticks when we are certain want to generate links.

[NicolasHug]

Thanks for opening the issue.

I’ll copy my https://github.com/scikit-learn/scikit-learn/pull/14381#issuecomment-521676762

(About using single backticks by default): As previously said, this is risky. That will link to things that should not be linked, you and I experienced it in the visualizer PR and plot.

I’d rather risk having no link than having a bad link. A link shows intent. It means “look here, you’ll find useful information”. Landing to a bad page will only add confusion to readers.

I really don’t understand why we want to go against the rst spec here. Yes, the rst standard can be a huge pain sometimes, but patching it seems like a bad idea to me.

[thomasjpfan]

Don’t have a strong opinion. so :py: does the linking to code and modules?

I mistyped. We still need :class:, :term:, :mod:, etc. (The default domain is :py:.)