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:
- The first step consists in analyzing the code included in a list of fortran files.
- The module
numpy.f2py.crackfortran
first indexes all fortran entities (modules, functions, calling arguments, etc).- Then all comments associated to identified entities are extracted to get complementary information.
- 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:
sphinxfortran.fortran_domain
: manual documentation of fortran code.sphinxfortran.fortran_autodoc
: auto-documentation.
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 variablefortran_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 directiverubric
(lightweight title in bold)."title"
: uses a conventional title (text with underlining, whose character is defined by ufortran_title_underline
).
-
fortran_title_underline
¶ Character used for underlining (default
"-"
) iffortran_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:
(seefilter_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.