Doxygen – Fortran-tooling

Tools

The Doxygen tool is a widely-used tool for automatically generating documentation from a codebase. It

Prerequisites

Min reqs:

Python >= 2.7
GNU tools flex, bison, libiconv and GNU make
cmake >= 3.14

For all features: - Qt >= 5.14 - A latex distribution - Graphvix >= 2.38 - Ghostscipt

Installation

Installation is done from source via the Doxygen download page.

Download the latest version for your operating system from that page, and follow the extensive installation instructions provided by Doxygen.

Note: Mac users can install vie Homebrew with brew install doxygen

Use

The User Manual is well documented and explains how the documentation keywords are read from docstring blocks.

There is a brief note on the specific comment style required for Fortran comments in the Documenting the code section. A comment block readable by Doxygen begins with !> or !<, and can be continued over multiple lines with !! or !>. The usual Doxygen keywords then apply within these blocks.

An example subroutine would look like:

!> @brief    Write results to an output file
!! @details  Writes the generated mesh to a specified output file
!!
!! @param num_nodes        Number of nodes to write to the output file
!! @param num_elements     Number of elements to write to the output file
!! @param element_to_node  Values of the elements to write
!! @param coordinates      Co-ordinates of the node points to write
!! @param nodal_value_of_f Nodal value of f
!! @param file_io          Output file
subroutine write_output_file(num_nodes,num_elements,element_to_node,coordinates,nodal_value_of_f,file_io)
    implicit none

    integer, intent(in) :: num_nodes,num_elements,element_to_node(3,mxp),file_io
    real, intent(in)    :: nodal_value_of_f(mxp), coordinates(2, mxp)
    !...
end subroutine

How we are using it

Our Doxygen configuration is defined in our Doxyfile

Markdown preprocessing

To allow us to reuse the same markdown files for both our Ford and Doxygen documentation, we are making use of the preprocessing capabilities of Doxygen. In our Doxyfile We have specified the following config.

ENABLE_PREPROCESSING = YES
FILTER_PATTERNS = *.md=./documentation/doxygen/format_markdown_for_doxygen.sh

This causes preprocessing to be run against all *.md files that have been discovered and not excluded by us. This preprocessing is defined within format_markdown_for_doxygen.sh which removes any Ford specific configuration. For example,

---
title: Tools
---

and uncomments any Doxygen config blocks. For example,

<!-- Doxygen config
@page doxygen Doxygen
@ingroup documentation
-->

becomes

@page doxygen Doxygen
@ingroup documentation