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:
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).
Checking to-do list in the documentation¶
If you are willing to contribute, you can check the to-do list for the documentation: here.
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:
#####################
# pyCIF config file #
#####################
# Define here all parameters for pyCIF following YAML syntax
# For details on YAML syntax, please see:
# http://docs.ansible.com/ansible/latest/YAMLSyntax.html
###############################################################################
# pyCIF parameters
###############################################################################
datavect:
components:
meteo:
plugin:
name: CHIMERE
version: std
dir: /tmp/PYCIF_DATA_TEST/CHIMERE/ACADOK
file: 'METEO.%Y%m%d%H.3.nc'
file_freq: 3H
fluxes:
plugin:
name: CHIMERE
type: fluxes
version: AEMISSIONS
dir: /tmp/PYCIF_DATA_TEST/CHIMERE/ACADOK
file: 'AEMISSIONS.%Y%m%d%H.3.nc'
file_freq: 3H
parameters:
CH4:
plugin:
name: CHIMERE
type: fluxes
version: AEMISSIONS
err: 1
file_freq: 3H
hresol: hpixels
nlev: 17
tresol: 2H
vresol: vpixels
###############################################################################
# http://community-inversion.eu/documentation/plugins/obsoperators/standard.html
obsoperator:
plugin:
name: standard
version: std
autorestart: false
datef: 2011-03-22 09:00:00
workdir: /tmp/CIF//.tox/py38/tmp/fwd_ref_chimere
datei: 2011-03-22 00:00:00
