[MRG] MNT DOC Fix the single backtick issues

[adrinjalali]

This is to fix the WARNING: 'any' reference target not found issues while making the documentation.

[adrinjalali]

This should substantially reduce the warnings. I'll leave the ones not addressed here for another PR, already kinda touching quite a few files here.

I've gone through the changes once manually, and fixed the long line issues, shouldn't be too far from an acceptable one.

@thomasjpfan wanna have a look?

[jnothman]

This is not the point imo. We want to be able to use single backticks for code formatting

[adrinjalali]

Then the question is do we warn on an unresolved one or not. First the answer was no (what @thomasjpfan had), and then we talked about it and it didn't seem like a good idea to not warn on them, cause sometimes that's just a typo and it should be fixed, or it's the wrong address or whatever. To get those warnings, the warnings were enabled, but we decided to fix the single backticks which result in warnings later.

[thomasjpfan]

The single backticks is doing too much, since we set the default role to 'any'. The "cleanest" resolution to this is to set all single backticks to code. If a user wants to reference the glossary or python method, they need to be explicit. (Use :term: or :py:)

[adrinjalali]

The single backticks is doing too much, since we set the default role to 'any'. The "cleanest" resolution to this is to set all single backticks to code. If a user wants to reference the glossary or python method, they need to be explicit. (Use :term: or :py:)

I like this alternative too, but this also means a whole bunch of links in our docs will become simple code.

[jnothman]

I think it's really nice not having to be explicit, as it gets in the way of readability for things like class names, but I'm okay with it (i.e default_role = code)

[adrinjalali]

@thomasjpfan should we (i.e. you :D, I'm not sure how you did that magic) again revert to ignoring these warnings and considering them code then?

[thomasjpfan]

@adrinjalali I’ll remove the warnings. We should also add py and term roles to items that need it.

[thomasjpfan]

There are only a few glossary references. But there are 278 resolved references to python functions/classes. Adding py in that many places would make docstring harder to read.

From what I recall from the sprint, the biggest concern was as follows: when someone wants to reference something but misspelled so it turns into code.

Since adding py or using double backticks everywhere would make the docstring less readable, I think we should let misspelled references go through. I do not think a misspelled reference that turns into code will subtract too much from the docs. Adding more noise such as py and double backticks would subtract from the readability.

With this, I propose we keep what we have now on master and remove the warnings we currently have for unresolved references.

[jnothman]

Misspellings are great. They help people contribute ;)