With a little nip here, a touch of tuck there, and some overall clean up the big change for making the linting code more modular and less ugly has been completed. This seemed to go exactly as I was planning on and I didn’t manage to distract myself with something shiny and send myself down a tangential path to blocking progress, so that’s also a net win.

There is now a new class named LinterBase which is the core of all lint operations, with subclasses specializing it to perform some specific check. The linting command creates instances of all of the classes that represent lint operations to be carried out, and then one by one it obtains views into the files to be linted and passes that to a method in each linter object.

Once this has been completed for all files and all linters, the list of linters is scanned one more time in order to gather the final results, which are a list of zero or more issues (containing context information and messages) which are then compiled into a report by some new code and displayed in a panel.

Some lint operations may only require access to the help index to perform checks, in which case they can override the __init__ method to kick off their checks and not have to do anything further. Other operations may require gathering information from all help files before being able to do any analysis, in which case they can capture information as they’re passed files and then do the final check once all files have been handled.

Currently the linters in place are a third option, which only need information from the current view (along with the help index) in order to find problems, so they override only the method that gets told about each file as it’s processed. Naturally any combination of these is also possible.

In order to verify that everything works as expected, along with implementing a simple class for detecting if there are any links to topics which don’t exist in the index, there is also a a test for anchors that appear in help files but not in the index as well, which may indicate topics of interest that have not yet been linked.

This is two separate classes even though the only difference in operation is the scope to look for and the body of the message that is generated. In the future this will be merged together to make the code clean, but for the time being I’m leaving it this way just because it helps to demonstrate how everything is supposed to hang together.

For the help currently in the hyperhelp package, the result of the current set of lint operations looks like this:

Linting in help package: hyperhelp

help_on_help.txt:
    warn 95:18 link references unknown anchor 'commands'
    warn 108:62 link references unknown anchor 'table of contents'

index.txt:
    warn 32:11 link references unknown anchor 'Help Index'

syntax.txt:
    warn 26:48 link references unknown anchor 'hyperhelp_date_format'
    warn 116:65 link references unknown anchor 'Intro'
    warn 94:6 anchor 'snake_case' is not in the help index
    warn 94:22 anchor 'periods.as_spaces' is not in the help index

style.txt:
    warn 3:3 anchor 'Style Conventions' is not in the help index

8 warnings, 0 errors

I have some ideas for some more lint tests which I think will be the next thing on the list of items to implement, along with the ability to also jump between links in the current buffer along with anchors, to make help browsing more productive.