Fordoctest: A Python CLI software to test that your code is correctly documented

Since I migrated from Python to Fortran I’ve missed the nice tooling that the former has around it. Luckily with huge efforts the Fortran community is getting on level with projects like fpm and FORD. One thing that I couldn’t find an equivalent to is pydoctest (pydoctest · PyPI) which screams at me whenever my documentation is poorly written (or absent). Including it on my CI builds helped me to assure that all my code is correctly documented.

For this reason, I decided to start a similar-in-heart project to use on my CI builds fordoctest:

Right now it is a very basic package on an early-alpha stage, but with the intention of getting bigger and a useful tool for the whole community!

On this version fordoctest takes all the same cli arguments as FORD (because it takes it’s cli options to generate a Project object) and does some basic analysis (which is enough for my usage, but can and should be extended). Upon running it will spit out warnings whenever there is

  • More than one module per file
  • Undocumented:
    • Isolated procedures
    • Modules
    • Module contained procedures
    • Procedure’s arguments

More details of what I expect to reach to is in the project README file and it’s issues.

Hope it can be useful for anybody else, and I will happily read recommendations or opinions about this!