Detect invalid role targets

[ezio-melotti]

trafficstars

Currently it's possible to refer to functions, methods, classes, etc. that don't exist, using :func:`not_existing_function()`. This is sometimes done intentionally, but other times the target is invalid because of a misspelling or because the package/module/class name is missing.

It might be helpful to detect and report these, perhaps with severity=0.

This came up in https://github.com/python/cpython/pull/92309#discussion_r866487363

[JulienPalard]

TIL it's already handled by Sphinx but not enabled by default: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky

Sadly on cpython it detects thousands of them, most are expected, like:

c:identifier reference target not found: va_list
c:func reference target not found: malloc
c:func reference target not found: free

Many removed things in old whatsnew, and so on...

I don't know if there's any value in using :c:func:`malloc` over ``malloc`` though.

[ezio-melotti]

If something is already reported by Sphinx as an error/warning, should sphinx-lint still check for it? On one hand it would be useful since it will allow to catch mistakes early without having to build the docs, on the other hand it makes the implementation of sphinx-lint more complex.

I was wondering the same thing in https://github.com/sphinx-contrib/sphinx-lint/pull/27#discussion_r867758258, where several cases are already caught by Sphinx.

[JulienPalard]

There's a way to choose: as sphinx-lint could be used by an IDE to highlight errors, all errors are usefull but it have to be fast and it have to be able to work on a single file.

Detecting invalid targets is not fast and does not work on a single file, so I would be against implementing it in sphinx-lint, but other fast tests are OK (but not a priority) to me even if they duplicate errors already seen by Sphinx.