https://github.com/fedebenelli/fordoctest

Assure standarized Fortran documentation with tets!
https://github.com/fedebenelli/fordoctest

documentation documentation-tool ford fortran python

Last synced: 2 months ago
JSON representation

Assure standarized Fortran documentation with tets!

• Host: GitHub
• URL: https://github.com/fedebenelli/fordoctest
• Owner: fedebenelli
• License: mpl-2.0
• Created: 2024-02-09T03:20:40.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2024-02-19T22:39:01.000Z (11 months ago)
• Last Synced: 2024-10-08T04:41:51.005Z (3 months ago)
• Topics: documentation, documentation-tool, ford, fortran, python
• Language: Python
• Homepage:
• Size: 478 KB
• Stars: 4
• Watchers: 1
• Forks: 0
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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](https://github.com/jepperaskdk/pydoctest))

in Python. `fordoctest` aims to be an equivalent tool for Fortran documentation.

## What does it do?

### Running

```bash

fordoctest  [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](docs/media/example_warnings.png)

### 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:

```bash

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

```