Skip to content

fedebenelli/fordoctest

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

fordoctest

Assure Fortran documentation consistence.

Motivation

As a project increases in size, it is harder to track the quality of the present code. In the case of functionality unit testing and coverage metrics can be enough to ensure there are no problems. But keeping track of correct documentation needs even more meticulous work, external tools can be used to help this process (like pydoctest) in Python. fordoctest aims to be an equivalent tool for Fortran documentation.

What does it do?

Running

fordoctest <ford_project_file> [ford_flags]

Right now fordoctest is in a pre-alpha state, it will check on all the source files included in a FORD file and send a warning if any of the following cases occur:

  • More than one module per-file
  • Undocumented:
    • Isolated procedures
    • Modules
    • Modules procedures
    • Procedures arguments

The output of `fordoctest will be something like:"

example output

What it aims to do

fordoctest aims to be a complete tool used in Fortran projects CI systems that can assure that all the code is correctly documented, and maybe also include extra checks like file headers, file naming checks, usage with other tools beside FORD, like Doxygen and Sphinx. We'll consider fordoctest to be in beta-stage once:

  • It becames FORD agnostic (right now it fully depends on the FORD cli parser so it's hard to easy add up methods)
  • Includes documentation checks of all the different kinds entities (like not included yet, derived types)
  • Include documentation restrictions (like forcing imperative verbs in a procedure documentation)
  • Fully tested with coverage of at least 90%

Installation

Since this is still an alpha release, we haven't yet released an installable on PyPI, but the development version can be installed with pip with:

pip install git+ssh://[email protected]/fedebenelli/fordoctest.git