Contributing to the documentation

The documentation is written in reStructuredText (rst) and built using the Python tool Sphinx. Sources for the documentation are provided within the CIF Git repository.

Locally compiling the documentation

Requirements

To contribute to the documentation the following softwares need to be install on your system:

  • Sphinx: automatic generation of html pages from rst files

  • Graphviz: embed graphics in the documentation

  • pycif: the CIF python package needs to be properly installed on your system to automatically build from modules

Compiling commands

Once Sphinx and Graphviz installed, you should be able to compile the documentation source files into html locally. To do so, type:

cd CIF_ROOT/docs
make html

Then, you can simply open html files generated in CIF_ROOT/docs/build/html/ in any web browser.

It is recommended to re-compile the documentation from scratch time to time:

cd CIF_ROOT/docs
make clean

Adding new files in the documentation

New files should be added in relevant sections and link to the corresponding table of content. Tables of contents are generally placed in the index.rst file in each sub-folders of the documentation. Therein, the file name should be added below the command .. toctree:: alongside existing files (the rst extension is not mandatory in that command).

Automatic construction from codes

The automatic documentation from codes is available here

Class of plugins

Type of plugins can be described by a full description, giving e.g., information about the expected structure, functions, etc. Examples are available in pycif/plugins/modes/__init__.py. Any help to improve these descriptions is welcome.

Individual plugins

The documentation is designed to include information in the pycif plugins directly and automatically. To allow this feature to work properly, the __init__.py file of the plugin being documented should include:

  • a docstring header: i.e. some rst compatible text at the very top of the file, embraced by “””:

    """
    This is a short description of my awesome plugin.
    
    I can use rst syntax in there, which will automatically compile in the documentation
    """
    

    the result will be inserted in a Description section of the corresponding entry of the documentation.

    Note

    Please note that if you need sub-sections in the description section, you should use the dot .......... to underline sub-titles.

  • a dictionary input_arguments: this dictionary is both used to define default values and document arguments that are needed in the configuration file; for each entry, you can add a “doc” entry, including a string describing the corresponding argument:

    input_arguments = {
        "some_argument": {
            "doc": "some description",
            "default": None if mandatory else a default value,
            "accepted": a python type that the argument should fit
        }
    }
    

    Some plugins may require sub-paragraphs to be properly defined. This can be done as follows:

    input_arguments = {
    
        "some_argument": {
            "doc": "some description",
            "default": None if mandatory else a default value,
            "accepted": a python type that the argument should fit
        },
        "some_subparagraph": {
            "doc": "Documentation of the paragraph",
            "default": None (must be None here),
            "optional": True or False,
            "structure": {
                "sub-arguments1": {
                    "doc": "some description",
                    "default": None if mandatory else a default value,
                    "accepted": a python type that the argument should fit
                },
                "sub-arguments2": {
                    "doc": "some description",
                    "default": None if mandatory else a default value,
                    "accepted": a python type that the argument should fit
                },
                "some_subsubparagraph": {
                    ...
                }
            }
        }
    }
    

Proposing tutorials

Tutorials are critical for new users and developers to start working with the CIF efficiently. They should encompass as many situations as possible. Experienced users/developers are encouraged to share their experience and explain how to tackle some specific difficulties they met in using the system.

Rules

  • Tutorials should be dedicated to a very specific problem (coding one type of Plugins, using one feature, etc.)

  • Tutorials should be concise and precise

  • Illustrations are worth a thousand words: include examples of codes, Yaml, etc.; when doing so, include long pieces of code or Yaml in separate files and use the command:

    .. literalinclude:: example_of_code.py
        :linenos:
        :language: python
    
  • Tutorials should remain up-to-date: their contributors are encouraged to check that past tutorials they wrote are still valid; in any case, please provide at least the last version of the CIF for which they where tested and/or a corresponding date

Extra functionalities

Hide/Show sections

It is possible to embed part of your text in order to hide them by default and the reader can display them by clicking on a small arrow. The syntax do do so is:

.. container:: toggle

  .. container:: header

    HEADER TEXT TO BE DISPLAYED ANYWAY

  Some text that will be hidden. It can include any other rst directive, such as source codes.

  .. code-block:: yml

    model :
      plugin:
        name    : CHIMERE
        version : std

This will display as follows:

HEADER TEXT TO BE DISPLAYED ANYWAY

Some text that will be hidden. It can include any other rst directive, such as source codes.

model :
  plugin:
    name    : CHIMERE
    version : std

Insert Yaml code and sub-sets of Yaml files

A feature has been implemented to insert the content of a Yaml and possibly only display part of the Yaml. The syntax reads as follows:

.. yml-block:: /yaml_examples/chimere/config_fwd_ref_chimere.yml
    :keys: verbose, logfile, workdir, datei, datef

The file to be given should be included in the sources of the documentation. The path is given relative to the root of the documentation sources. In the example above, the file points to the path ${CIF_ROOT}/docs/source/yaml_examples/chimere/config_fwd_ref_chimere.yml.

The argument :keys: is optional. If not specified, the whole file is inserted. Otherwise, only the mentioned keys (separated by a comma) are included.

It is possible to include only part of the structure of a given paragraph by specifying the “path” in the Yaml separated by /

For instance, the following example only displays a subset of the datavect paragraph.

.. yml-block:: /yaml_examples/chimere/config_fwd_ref_chimere.yml
  :keys: datavect/components/meteo, datavect/components/fluxes, obsoperator, datef, workdir, datei

This displays as follows:

datavect:
  components:
    meteo:
      dir: /tmp/PYCIF_DATA_TEST/CHIMERE/ACADOK
      file: 'METEO.%Y%m%d%H.3.nc'
      file_freq: 3H
      plugin:
        name: CHIMERE
        version: std
    fluxes:
      dir: /tmp/PYCIF_DATA_TEST/CHIMERE/ACADOK
      file: 'AEMISSIONS.%Y%m%d%H.3.nc'
      file_freq: 3H
      parameters:
        CH4:
          err: 1
          file_freq: 3H
          hresol: hpixels
          nlev: 17
          plugin:
            name: CHIMERE
            type: fluxes
            version: AEMISSIONS
          tresol: 2H
          vresol: vpixels
      plugin:
        name: CHIMERE
        type: fluxes
        version: AEMISSIONS
obsoperator:
  autorestart: false
  plugin:
    name: standard
    version: std
datef: 2011-03-22 09:00:00
workdir: /tmp/CIF//.tox/py38/tmp/fwd_ref_chimere
datei: 2011-03-22 00:00:00