Fortran extension to `sphinx.domains`¶

The module sphinxfortran.fortran_domain is an extension to Sphinx adding the FORTRAN “domain” (see the sphinx documentation on syntactic domains), and can therefore document FORTRAN codes.

Configure Sphinx¶

Just add sphinxfortran.fortran_domain to the list defined by the extension variable in the file conf.py sphinx configuration file (assuming the vacumm python package is available to you).

Syntax¶

This extension provides “guidelines” to declare (describe and reference) fortran entities (program, module, type, function, subroutine and variable), as well as “roles” to refer to the declared entities.

Directives¶

All directives are prefixed by f: to refer to the fortran domain.

Note

Thereafter, the brackets [] denote an optional argument.

All directives accept content to describe the entity, which will interpreted by sphinx. This description can also take advantage of docfields to describe the arguments of functions, subroutines and programs.

.. f:program:: progname¶

Description of a FORTRAN program. This directive accepts docfields.

Example:

.. f:program:: main

    This is the main program.

.. f:module:: modname¶

This creates a reference to a module and produces no output. It accepts the :synopsis: option to briefly describe the module in the modules index. It also defines the current module, like f:currentmodule.

Example:

.. f:module:: monmodule
    :synopsis: Statistics module

.. f:currentmodule:: [modname]¶

This directive produces no output, it makes of modname the current module: functions, subroutines, types and variables described in the following will be considered as belonging to this module. If modname is empty or equal to None, there is no more current module.

Example:

.. f:currentmodule:: mymodule

.. f:variable:: float myvar

.. f:currentmodule::

.. f:type:: [~][modname][/]typename¶

This directive describes a derived type in a module. It accepts the special docfield :f ...: to describe the fields of the module.

Example:

.. f:type:: mymod/mytype

    :f integer var1: Variable 1
    :f float var2: Variable 2

.. f:variable:: [type] [~][modname][/]varname[(shape)]¶

This directive describes a variable of a module. It accepts the following options:

- ``:type:``: Type of the variable (``float``, ``mytype``, etc).
  Si présent, un lien est créé vers ce type.
  The type can also be specified before the variable name.
- ``:shape:``: Shape in the form ``nx,ny``,
  which can also be declared after the name (in brackets).
  A reference to all variables found is created.
- ``:attrs:``: Additional Attributes (``in``, ``parameter``, etc).

Example:

.. f:function:: float myvar
    :shape: nx,ny
    :attrs: in

    Description of my variable.

.. f:function:: [type] [~][modname][/]funcname(signature)¶

This directive describes a function belonging or not to a module. It accepts the option :type: and uses docfields to describe his arguments, his calls and modules used.

Example:

.. f:function:: myfunc(a [,b])

    This is my primary function.

    :p float a: My first argument.
    :o integer b [optional]: My second argument.
    :from: :f:subr:`mysub`

.. f:subroutine:: [~][modname][/]subrname[(signature)]¶

This directive describes a subroutine like the directive f:function.

Example:

.. f:subroutine:: mysub(a)

    Description.

    :param a: My parameter.
    :to: :f:func:`myfunc`

The roles¶

The roles allow in rst language to refer to entities (program, function, etc.). They are used with a syntax like:

:role:`cible`
:role:`nom <cible>` # avec nom alternatif

Several have been defined with respect to fortran guidelines presented above.

:f:prog:¶: Reference to a program declared with f:program.

:f:mod::¶: Reference to a module declared with f:module.

:f:type::¶: Reference to a derived type declared with f:type.

:f:var::¶: Reference to a variable declared with f:variable.

:f:func:¶: Reference to a fonction or a subroutine declared respectively with f:function and f:subroutine.

:f:subr::¶: Alias for f:func.

It is possible to make reference to derived types, variables, functions and subroutines belonging to a module, with the typical following syntax:

monmodule/myfunction()

If a local function and the module have the same name, it is possible to use the following syntax if the current module is the same as the function module:

/myfunction()

If the / is omitted, the reference will focus on the local function and not that of the current module.

If the module is specified in the reference, it is possible not to display the name by prefixing "~":

:f:func:`~mymodule/myfunction`

The docfields¶

The docfields are rst tags of type field list, which are interpreted in the content of certain directives to describe the settings, options and other special fields.

The fortran domain allows a use pretty close to that implemented for the python domain.

There are two families of fortran docfields: one for functions and subroutines, and one for derived types.

Fonctions et subroutines family

For this family, the docfields are used to describe the mandatory and optional arguments, the modules used, the programs, functions and subroutines that call the current entity, and the functions and subroutines called by this entity. Some of them have aliases.

param (or p, parameter, a, arg, argument): Mandatory argument.
```
:param myvar: Description.
```
It is possible to specify the type, the size and special attributes in the declaration following the example below:

param mytype myvar(nx,ny) [in]:

Description.
type (or paramtype, ptype): Parameter type (eg: float). Reference is made to this parameter if present.
```
:type: float
```
shape (ort pshape): Shape of the parameter (dimensions are separated by commas).

shape: nx, ny
attrs (or pattrs, attr): Special Attributes (separated by commas).
```
:attr: in/out
```
option (or o, optional, keyword): Declaration of an optional parameter with a similar syntax to required parameters (param).
otype (or optparamtype): Its type.
oshape : Its shape.
oattrs` (or oattrs): Its attributes.
return (or r, returns): Variable returned by the function.
rtype (or returntype): Its type.
rshape: Its shape.
rattrs` (or ``rattrs): Its attributes.
calledfrom (or from): Functions, subroutines or programs calling the current routine.
callto (or to): Fonctions ou subroutines called by the current routine.

The docfiels are merged into one list for those mandatory, and another one for those optional, and their associated docfiels (type, dimensions et attributs) are deleted and inserted in the parameter declaration.

Note

In addition to these docfiels that are intepreted, you can add other of your choice. For example:

:actions: This function performs

    #) Une initialisation.
    #) Un calcul.
    #) Un plot.

:p float myvar [in]: Variable à tracer.
:use: Fait appel au module :f:mod:`mymod`.

Derived types family

These docfields describe the fields of derived types. They are inserted into the header of a f:type directive.

ftype (or f, typef, typefield): Fields of a derived type with a syntax similar to that of required parameters or routines (param).
ftype (or fieldtype): Its type.
fshape: Its shape.
fattrs` (or fattrs): Its attributes.

Example¶

**Programme**

.. f:program:: make_stats

    Programm for computing statistics calcul des statistiques

**Module** :f:mod:`mymodule`

.. f:module:: mymodule
    :synopsis: Main statistical module

.. f:variable:: nx
    :type: integer
    :attrs: parameter=5

    Zonal dimension.

.. f:variable:: sst(nx)
    :type: float

    SST du modèle.

.. f:type:: obs

    Type that describes observations.

    :f x(nx): zonal axis.
    :ftype x: float
    :f float sst(nx): SST

.. f:subroutine:: stats(data, b, [c, d])

    Description of the routine.

    :param obs data: Data to analyse.
    :p integer a(nx,5) [in]: Also mandatory.
    :o float c [optional]: Optional.
    :o d: Also optional.
    :from: :f:prog:`make_stats`.
    :to: :f:func:`rms`

**Module** :f:mod:`special_stats`

.. f:module:: special_stats

.. f:function:: rms(mod, obs, unbiased)

    Compute RMS errors.

    :p float mod(nx) [in]: Model outputs.
    :p float obs(nx) [in]: Observations.
    :p logical mask(\:) [in]: Mask.
    :o logical unbiased [default=.true.]: Biased?
    :r rms(nx): Computed RMS.
    :rtype rms: float
    :from: :f:func:`mymodule/stats` :f:func:`~mymodule/stats` :f:subr:`stats` :f:func:`stats`

.. f:currentmodule::

Which gives:

Programme

program make_stats¶

Programm for computing statistics calcul des statistiques

Module mymodule

mymodule/nx [integer,parameter=5]¶

Zonal dimension.

mymodule/sst (nx) [float]¶

SST du modèle.

type mymodule/obs¶

Type that describes observations.

Type fields:

% x (nx) [float] :: zonal axis.

% sst (nx) [float] :: SST

subroutine mymodule/stats(data, b[, c, d])¶

Description of the routine.

Parameters:

data [obs] :: Data to analyse.

a (nx,5) [integer,in] :: Also mandatory.

Options:

c [float,optional] :: Optional.

d :: Also optional.

Called from:
make_stats.

Call to:
rms()

Module special_stats

function special_stats/rms(mod, obs, unbiased)¶

Compute RMS errors.

Parameters:

mod (nx) [float,in] :: Model outputs.

obs (nx) [float,in] :: Observations.

mask (*) [logical,in] :: Mask.

Options:
unbiased [logical,default=.true.] :: Biased?

Return:
rms (nx) [float] :: Computed RMS.

Called from:
mymodule/stats() stats() stats() stats()

Note

Declared modules are listed in their index, and other fortran entities are also accesible from the main index.

Fortran extension to sphinx.domains¶

Configure Sphinx¶

Syntax¶

Directives¶

The roles¶

The docfields¶

Example¶

Fortran extension to `sphinx.domains`¶