Breaking changes to custom checkers

[vkbo]

I've been using sphinx-lint for a while to lint documentation for projects with many contributors, and I have a custom @checker decorated function to check header levels. Is it not a supported feature to be able to create custom checkers by adding the decorator?

I'm asking, because there have been several unannounced breaking changes to this, and I am getting rather frustrated with it. The latest breaking change, v0.6.8 -> v0.7.0, changed the type of one of the attributes from list to tuple. Recently, the import paths changed too.

If we're not supposed to create custom checkers, then that's fine. I'd just like to know.

[AlexWaygood]

Hi, I'm sorry we broke your code! We certainly didn't do so intentionally.

I think a few of the recent changes you mention were as a result of various performance optimisations in the last few releases. The combined impact of these changes has made sphinx-lint around 5x faster when it checks CPython's Doc/ directory.

I'm a fairly new maintainer at sphinx-lint, but I can't find any reference in our documentation to extending sphinx-lint with custom checkers. I believe sphinx-lint is a CLI tool that has no API, and that everything is an implementation detail. So, I believe we never intended to support what you've been doing — but I might be wrong.

[vkbo]

Yeah, I haven't been able to actually find the documentation, so I don't know. I was starting to wonder if importing the checker was supported or not.

Anyway, the only reason I needed to customise it was to support checking section/header levels, as explained here. It would be nice to have it as an optional check.

Edit: This is not the same feature as #5 by the way, but checking that headers use the syntax as recommended by the Python Dev Guide.

[AlexWaygood]

Yeah, I haven't been able to actually find the documentation

Yes, I believe the only documentation we have is the README, and admittedly there are some things that probably should be documented there which currently aren't

[AlexWaygood]

Have you considered contributing your custom checker to sphinx-lint itself? We might be interested in a PR like that :)

[vkbo]

It's part of two work projects, but that may not be a problem (I'll have to check). The code is pretty brute force to get the job done though. Not sure it's production quality. I'll look into it.

[vkbo]

Actually, the code isn't that bad. It just iterates through the lines and checks blocks of three lines for header consistency. It performs the following checks:

• header over- and underline must be identical
• header text and underline are not the same length
• missing blank line after header
• over- and underline header must use '#' (H1) or '*' (H2)
• underline header must use '=' (H3), '-' (H4), '^' (H5) or '"' (H6)
• header text should not end in punctuation
• first header must use '#' (H1) or '*' (H2)
• header level skipped, this is level H{curr}, previous was H{prev}

This should also satisfy #5, and probably has some additional checks that may or may not be strictly needed, like "missing blank line after header". I just like to keep the source of our docs readable 😃