readthedocs.org
readthedocs.org copied to clipboard
Docs: Remove rstcheck from linting
Proposing to remove rstcheck
from builds and tox.ini: Our documentation is already built with Sphinx and will fail if reST files do not compile.
The tool rstcheck
is supposed to check reStructuredText but it doesn't work without a huge amount of exceptions for the many extensions added to Sphinx.
This requires a lot of maintenance but it also makes us ultimately not rely on rstcheck
since it won't check all the roles and directives that are omitted via .rstcheck.cfg
I'd also like to add that as a contributor, I spent a lot of time figuring out how to fix errors in :external+<mapping-key>:ref:<label>
because the location of the file isn't obvious.. a copy of the file can exist at any point in the documentation folder hierarchy.
Drawbacks
I don't think removing it has any draw-backs, since we ultimately rely on builds from Read the Docs, and even an entry in tox.ini will build the documentation and fail when there are warnings.
rstcheck
might be great for a quicker validation of large documentation builds, but since we are doing the other builds no matter what, I don't think we are really benefiting from this aspect.
Did I miss something here?
Honestly, I don't even remember why we added it. Also, I don't remember what are the issues it has found all this time we have had it enabled. I only remember it because I've had to add an exception 😄 . That said, I think it's fine removing it.