Better docstring linting tool #648
Description
Is your feature request related to a problem? Please describe.
`this` is a reference in rst. When it's written in a docstring, sphinx tries to find a reference for `this`, and depending upon the Python domain, could implicitly assign a role like :py:meth:`this`. However, some references can be ambiguous, particularly when they interact with intersphinx, some inheritance logic, or are to a private function.
This results in a lot of errors about missing reference targets or ambiguous reference targets in sphinx. The warnings in sphinx don't have a line number referring to the original file, but to the generated documentation, which makes them particularly difficult to diagnose.
Describe the solution you'd like
Hopefully there's a better practice that will make the reference-based issues less common, and a pre-commit that enforces that better practice.
We currently use sphinx-lint and a few from `pre-commit/pygrep-hooks.
Additional
Once we have such a tool, over time, we should remove the suppress_warnings entries in docs/conf.py and hunt down the problems.