Auto-documenting fortran codes

Sphinx extension sphinxfortran.fortran_autodoc provides directives for semi-automatically documenting (F90+) fortran codes. It helps describing et referencing programs, modules, derived types, functions, subroutines and variables in documentatin generated by sphinx.

Note

You need modules numpy et sphinxfortran.fortran_domain tu use this extension.

How it works

The process of auto-documentation is the following:

  1. The first step consists in analyzing the code included in a list of fortran files.
    1. The module numpy.f2py.crackfortran first indexes all fortran entities (modules, functions, calling arguments, etc).
    2. Then all comments associated to identified entities are extracted to get complementary information.
  2. The second step auto-documments on demand an entity indexed during the first step, using the sphinx extension fortran_domain.

Usage

Configure Sphinx

You can configure sphinx by editing the file conf.py (see documentation).

You must first load the extension:

Just add the name of the two modules to the list of the configuration variable extension.

Then, you must specify the list of fortran source files in the configuration variable fortran_src.

Here are the available configuration variables.

fortran_src

This variable must be set with file pattern, like "*.f90, or a list of them. It is also possible to specify a directory name; in this case, all files than have an extension matching those define by the config variable fortran_ext are used.

Note

All paths are relative to the sphinx configuration directory (where the conf.py is).

fortran_ext

List of possible extensions in the case of a directory listing (default: ['f90', 'f95']).

fortran_encoding

Character encoding of fortran files (default : "utf8").

Note

It is strongly recommanded to encode your sources with a set of universal character as UTF-8.

fortran_subsection_type

Section type for the documentation of modules and files. Choice:

  • "rubric" (default) : use directive rubric (lightweight title in bold).
  • "title" : uses a conventional title (text with underlining, whose character is defined by u fortran_title_underline).
fortran_title_underline

Character used for underlining (default "-") if fortran_subsection_type = "title".

fortran_indent

Indentation string or length (default 4). If it is an integer, indicates the number of spaces.

Inserting an auto-documentation

The insertion of an auto-documentation can be chosen with the following diectives.

.. f:autoprogram:: progname

Document a program.

.. f:autofunction:: [modname/]funcname

Document a function.

.. f:autosubroutine:: [modname/]subrname

Document a subroutine.

.. f:autotype:: [modname/]typename

Document a derived type.

.. f:autovariable:: [modname/]varname

Document a module variable.

.. f:autovariable:: modname

Document a module. This directive accepts options :subsection_type: and :title_underline:.

.. f:autosrcfile:: pathname

Document programs, functions and subroutines of a source file. This directive accepts options ::search_mode: and :objtype: (see filter_by_srcfile()). Example:

.. f:autosrcfile::  myfile.f90
    :search_mode: basename
    :objtype: function subroutine

Warning

Untested directive!

Optimize the process

To optimize the process of documentation, it is recommended to follow some rules when commenting FORTRAN codes: these comments provide a way to better decribe fortran entities, and are interpreted in rst language.

Header comments

The comments in the modules headers, up to the first line of code, are are systématically used. Example:

module mymod

! This is my **super** module and its description

integer :: var

end module mymod

In the case of programs, functions, subroutines and types, comments are used if they start immediately after the declaration line. Examples:

subroutine mysub(a)
! Description
end subroutine mysub

type mytype
    ! Description
    integer :: var
end type mytype

Inline comments

These comments are in a line of code. They are used to declare fields of derived types, module variables et arguments of functions and subroutines. Example:

type mytype
    integer :: myvar &, ! Description1
        &      myvar2   ! Description2
end type mytype

subroutine mysub(a, b)
    ! Description mysub
     integer, intent(in) :: a ! Description a
     real, intent(out) :: b   ! Description b
end subroutine mysub

Warning

There must have only one declaration of variable or field a description comment is specified.