sphinxfortran_ng

sphinxfortran_ng is a Sphinx extension that provides a Fortran domain and an autodoc-like mechanism for documenting Fortran source code.

It allows Fortran modules, subroutines, functions, variables, and derived types to be documented directly from source files, using familiar Sphinx directives and roles.

The extension is designed to integrate naturally with standard Sphinx workflows and follows the conventions of sphinx.ext.autodoc where possible. It is an improved version of the original sphinx-fortran project, whose parser is itself a trimmed copy of the crackfortran module of NumPy/f2py.

Features

  • Fortran domain (f:) with directives and cross-referencing roles

  • Autodoc-style directives (f:automodule, f:autoroutine, …) for Fortran source code

  • Extraction of documentation from ordinary Fortran comments, written in reStructuredText, with no special comment marker required

  • Argument types, shapes, intent, optional arguments and default values are read from the declarations, so they never get out of sync with the code

  • Support for modern Fortran (90 and later): modules, derived types, generic interfaces, bind(c) variables, use ... only renaming

  • Clean integration with HTML, LaTeX, and other Sphinx builders

How it works

Documenting a Fortran module involves three cooperating stages:

  1. Parsing – at the builder-inited event, every file found through fortran_src is parsed by sphinxfortran_ng.crackfortran_for_sphinx and its comments are attached to the parsed blocks by F90toRst.

  2. Generation – when an f:auto* directive is met, F90toRst converts the requested object into plain reStructuredText that uses the manual f:module, f:function, f:variable, … directives, and inserts it in the document.

  3. Rendering – the directives of the Fortran domain (FortranDomain) turn that text into signatures, field lists, index entries and cross-reference targets.

The two halves are documented separately: Fortran Autodoc (stages 1 and 2) and Fortran Domain (stage 3). Because stage 2 produces text that stage 3 understands, everything the autodoc directives can do can also be written by hand.

A first example

Given this Fortran source, in which the documentation is written as plain comments right after the declaration line it describes:

module sf_arrays
!SciFortran module for array creation and manipulation
  implicit none
contains

  function arange(start,num) result(array)
  !
  !Returns an array of :f:var:`num` integers starting with :f:var:`start`
  !
    integer :: start       !First element of the array
    integer :: num         !Length of the array
    integer :: array(num)  !The integers in [:f:var:`start`, :f:var:`start` + :f:var:`num` - 1]
    integer :: i
    forall(i=1:num) array(i) = start+i-1
  end function arange

end module sf_arrays

the two lines below are enough to document the module:

.. f:automodule:: sf_arrays

which yields, for the function, the same result as writing by hand:

.. f:function:: arange(start, num)

   Returns an array of :f:var:`num` integers starting with :f:var:`start`

   :p integer start: First element of the array
   :p integer num: Length of the array
   :r integer array(num): The integers in [:f:var:`start`, :f:var:`start` + :f:var:`num` - 1]

Note that :p / :r fields, the argument types and the shape array(num) were all produced from the declarations; only the sentences were written by the author.

Important

Module, routine and variable names are stored in lower case by the parser. Always write them in lower case in the directives: .. f:automodule:: sf_arrays, not SF_ARRAYS.

Where to go next

Quick start

Install the extension, configure conf.py and build a first page.

Formatting Fortran (.f90) Code for Auto-Documentation

Start here when writing Fortran comments. The exact rules the parser follows, with the pitfalls that make a description silently disappear.

Fortran Autodoc

The f:auto* directives, their options and the configuration values.

Fortran Domain

The manual directives, the field lists, the roles for cross-referencing and the module index.

Examples

Walk-through of two real modules: a library of functions (SF_ARRAYS) and a module made of input variables (ED_INPUT_VARS), with the generated reStructuredText, each followed by its live rendering.

Known limitations

Known limitations and behaviours that differ from what one may expect, with workarounds.

Contents