Unresolved reference should have a visually different style.

[Carreau]

Related to #22,

we need a way to clearly see unresolved single backticks reference instead of having them looks like either emphasis or codeblock.

nitpicky might not be a direct path forward as it creates too many errors.

[larsoner]

From what we discussed, a first, low-effort (maybe) solution would be CSS.

Next would be to hook into docutils to figure out when/where the "unresolved link" nodes are created and you could maybe emit useful logging messages.

Sound about right?

[QuLogic]

nitpicky might not be a direct path forward as it creates too many errors.

Matplotlib uses nitpicky = True, but with this complicated extension in order to ignore all existing warnings, and work on it piecemeal. Maybe this would be useful to be used elsewhere.

[Carreau]

I want to address first the problem visually when you view a page to nudge people, but yes having build fail in the long run woudl be good.

[bsipocz]

astropy and related packages do nitpicky and fail with -W, but in practice whenever there is a new broken sphinx link it requires someone with some sphinx knowledge/or knowledge how to read the sphinx log to know which thing caused the issue. So 💯 on having broken sphinx links rendered differently than double backticked emphasis.

[larsoner]

FWIW in MNE-Python when people do stuff wrong we use a little grep to try to find the offending line within the hundreds of logged lines

https://github.com/mne-tools/mne-python/blob/7f2c9315dc6f9709f480ac711ebe30368b052c36/.circleci/config.yml#L250-L254

We could probably turn this into a little sphinx extension that notices these and replicates them at the end of the build, so instead of seeing just:

embedding documentation hyperlinks for auto_examples... [100%] xhemi.html
Build finished warnings treated as errors.  <-- or whatever Sphinx writes
The HTML pages are in _build/html.

we could add at the end

Warnings treated as errors:
- ...
- ...

then you don't have to scroll hundreds of lines up in the logs.

[larsoner]

... the code for this probably lives in the matplotlib extension somewhere so maybe we can/should build off of that.