Automated documentation checks
I often see other projects use either git commit hooks or CI jobs (or both) to check documentation coverage. We should consider implementing this for Finesse 3.
The scope for coverage checks is vast and can range from simply testing for the presence of docstrings to requiring particular patterns within docstrings to be present. I think we can start with the basics first and adapt @samuel.rowlinson's
check_missing.py script to run either on pre-commits or as a CI job.
If we choose to adapt Sam's script, I think it needs some slight changes:
- It should return a non-zero exit code if there are issues, else
0. CI jobs can use this to indicate failure.
- It should summarise the issues in a table at the end, rather than (or as well as) a dump of every issue.
- We should be able to define a list of classes/functions/etc. that MUST have their own dedicated documentation pages. Ideally this should allow wildcards like
As for whether these checks are pre-commit or CI, I guess it comes down to whether we care about these problems being fixed before other developers look at the code, or only before users use the code.
I'm happy to work on this, but I think I recall Sam mentioned he was building a separate project out of his script so perhaps he can give an update on the status of that here before I start...