GeezerVison

Sorry if I'm misinterpreting something here, but wouldn't this remove directives like .. describes:: or .. class:: too? Or is that intentional?

You're understanding it correctly, it removes a bit too much. But the documentation tells comments are Every explicit markup block which isn’t a valid markup construct.

an explicit markup is:

An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation.

According to the ref, explicite markup are

used for footnotes, citations, hyperlink targets, directives, substitution definitions, and comments

in directives there's potentially a lot, as it's possible to add new directives, like versionchanged in our doc.

So we have like three choices:

• Keep it simple and introduce some false negatives (current version)
• Do it right with no false positives and no false negative, it's probably doable as we have the exhaustive list of directives already hardcoded in rstlint.py
• Keep it simple, the other way around, and introduce some false positives.

I'm really not in favor of false positives: it's a burden for contributors. False negatives are OK though: if an rst error is introduced it'll still fixable later.

I'll try myself at the "do it right version" today to see if it's worth it.

Was not that hard, probably worth it, I pushed it.

Thanks for your patience and explaining it to me :).