Snowtools code Documentation

The documentation is managed through Sphinx <www.sphinx-doc.org> documentation generator.

Where to find the documentation

If you are reading these lines, you may have found the documentation. Anyway, snowtools documentation could be accessed in two ways:

  • Get pre-generated documentation

  • Generated through code source

Documentation access

If you are at Meteo-France, Pre-generated documentation is accessible on http://intra.cnrm.meteo.fr/cen/snowtools/.

Generate documentation

Documentation can be generated directly from source repository. It could be generated in two formats : HTML and PDF.

To do so, go to the doc folder and use make <format> where <format> could be either html or pdf. The documentation will be generated in doc/_build/<format>.

Note that this generation will require some packages to be installed:

  • all snowtools dependencies (this includes a correct installation of vortex)

  • Python 3.7 or later

  • sphinx

  • The sphinx-fortran extension (installable with pip install sphinx-fortran but the pipy version is quite old, so we encourage you to install the last version available at https://github.com/VACUMM/sphinx-fortran with pip install git+https://github.com/VACUMM/sphinx-fortran)

Code documentation

Each modification or code addition must be documented through docstrings. In python code, it should be inserted between """ immediately after function or class definition. As it will be parsed by sphinx for generation documentation, you are highly encouraged to use the reST/sphinx documentation format. You can add unit tests through doctests (see the corresponding documentation for more details).

Note that functions or classes without docstring will not appear in this documentation.

Documentation format

The docstrings will be parsed by Sphinx as reStructuredText format. More details on the format could be found on the links below:

Here is an example of documentation as it should take place in snowtools:

class MyClass(utils.prosimu):
    """This is a useful class for doing a lot of things
    It extends the :class:`utils.prosimu` class with
    very useful functions.

    :param fn: filename to read
    :type fn: path-like (str)
    :param n: an integer
    :type n: int
    """

    def __init__(self, fn, *args, n=0, **kwargs):
        super().__init__(fn, *args, **kwargs)
        self.n = n

    def useful_function(self, n):
        """
        My useful function. Do nothing.

        :param n: an input parameter
        :type n: int
        :return: always 0
        :rtype: int
        """
        return 0

Organize the documentation

The documentation is generated with sphinx automatically. However, it remains necessary to organize a little bit all the documentation we have. If you modify an existing module, don’t worry, the module should be already known by the documentation and your added code will be automatically taken into account.

If you add a brand new module, you have to tell sphinx where to document this module. The structure is in the doc/source folder and you have to add an automodule directive where you want your module to be documented, with the following syntax:

.. automodule: utils.prosimu
   :members:

Scripts documentation

If you add a new script, documentation can be generated by running the script with -h option.

To add a documented script :

  1. Add script path to doc/scripts_list.txt (file path)

  2. Add an include directive where you want in the documentation pointing to ./autoscripts/<fn> where <fn> is the script file path with / replaced by --

Fortran Documentation

Fortran documentation is done through sphinx-fortran add-on. Folder containing Fortran files are set in the doc/source/conf.py file and then it is possible to document a whole file with:

.. f:autosrcfile:: ../path/to/file.f90

or specific elements (program, module, subroutine, function) giving their name (and possibly the module name):

.. f:autoprogram:: progname

.. f:automodule:: modname

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

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

Note that elements included in programs, subroutine or functions are not documented (e.g. subroutine defined in a CONTAINS section of a program). Subroutines and functions that are placed inside a module are documented with the module documentation.

Warning: The modname has to be given in lower case letters, even if the original module name is written in upper case.