ptheywood
commented
2 years ago RST linters are a little sparser/more limited than I'd hoped, so don't appear too useful w.r.t this.
doc8 and rstcheck appear to be the main competing linters more recently, although both have had periods of inactivity. doc8 appears to be the most recently maintained of the linters.
doc8 mostly checks line length, white space and line endings, which I'm not sure are worthwhile enforcing.
rstcheck mostly warns about duplicate implicit targets and unreferenced labels, which again I do not feel are worth enforcing.
The use of symbols for heading levels in the RST files varies from file to file.
There is no strict symbol to heading level meaning in RST, instead the order within a document is important.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
We should aim to standardise this throughout the documentation to aid maintainability.
It may be worth investigating RST linters to enforce this / potentially automate conversion.