Quick start

This page goes from an empty Sphinx project to a rendered Fortran module in five steps.

Installation

$ pip install sphinxfortran_ng

The extension requires Python 3.8 or later and Sphinx. From a repository checkout, use pip install -e . instead. To build this documentation, install the requirements of the doc folder:

$ pip install -r doc/requirements.txt
$ sphinx-build -b html doc doc/_build/html

Configuring conf.py

Both extensions must be listed. The domain (sphinxfortran_ng.fortran_domain) creates the f: domain; the autodoc extension only adds its directives to it, so it does nothing on its own.

extensions = [
    "sphinxfortran_ng.fortran_domain",
    "sphinxfortran_ng.fortran_autodoc",
]

# Where to look for Fortran sources: files, glob patterns or directories
fortran_src = ["../src"]

# Extensions searched in directories (case does not matter)
fortran_ext = ["f90", "f95", "f03"]

The complete list of configuration values is given in Configuration values.

Note

Directories in fortran_src are not searched recursively. Add one entry per directory, or use a glob such as "../src/*/*.f90".

Commenting the source

Write the description inside the documented block, on the comment lines that immediately follow its first line, and describe each variable with a comment at the end of its declaration:

subroutine scale(x, factor)
!Multiplies :f:var:`x` in place by :f:var:`factor`.
  real(8), intent(inout)  :: x(:)   !Array to scale
  real(8), intent(in)     :: factor !Multiplicative factor
  x = x * factor
end subroutine scale

There is no !> / !! marker: those characters would be copied into the output. The full rules are in Formatting Fortran (.f90) Code for Auto-Documentation.

Using the directives

In any .rst file, document a whole module:

.. f:automodule:: mymodule

or pick individual objects:

.. f:autoroutine:: mymodule/scale

.. f:autotype:: mytype

.. f:autovariable:: beta

See Fortran Autodoc for every directive and option.

Cross-referencing

Anywhere in the documentation, whether in an .rst file or inside a Fortran comment:

See :f:mod:`mymodule`, :f:func:`scale`, :f:var:`beta` and :f:type:`mytype`.

Roles are listed in Cross-Referencing.

Rebuilding after a Fortran change

The Fortran files are parsed once, when the builder starts, but they are not registered as dependencies of the pages that use them. If you only edit a .f90 file, an incremental sphinx-build will consider the .rst pages up to date and skip them. Force a full re-read with:

$ sphinx-build -E -b html doc doc/_build/html

(or delete the _build folder, or touch the .rst page).