Auto-documenting fortran codes
==============================

Sphinx extension :mod:`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 :mod:`numpy` et :mod:`sphinxfortran.fortran_domain`
    tu use this extension.

.. highlight:: rst

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.

       a) The module :mod:`numpy.f2py.crackfortran` first indexes
          all fortran entities (modules, functions, calling
          arguments, etc).
       b) 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 :mod:`~sphinxfortran.fortran_domain`.




Usage
-----

Configure Sphinx
~~~~~~~~~~~~~~~~

You can configure sphinx by editing the file :file:`conf.py`
(see :sphinx:`documentation <config.html#build-config>`).

You must first **load the extension**:

- :mod:`sphinxfortran.fortran_domain`: manual documentation of fortran code.
- :mod:`sphinxfortran.fortran_autodoc`: auto-documentation.

Just add the name of the two modules to the list of the configuration variable
:sphinx:`extension <config.html#confval-extensions>`.

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

Here are the available configuration variables.

.. confopt:: 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 :confopt:`fortran_ext` are used.

    .. note::

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

.. confopt:: fortran_ext

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

.. confopt:: 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.

.. confopt::   fortran_subsection_type

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

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

.. confopt:: fortran_title_underline

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


.. confopt:: 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.

.. rst:directive:: .. f:autoprogram:: progname

    Document a program.

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

    Document a function.

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

    Document a subroutine.

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

    Document a derived type.

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

    Document a module variable.

.. rst:directive:: .. f:autovariable::  modname

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

.. rst:directive:: .. f:autosrcfile::  pathname

    Document programs, functions and subroutines of a source file.
    This directive accepts options :``:search_mode:`` and  ``:objtype:``
    (see :meth:`~sphinxfortran.fortran_autodoc.F90toRst.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
~~~~~~~~~~~~~~~
.. highlight:: fortran

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.