####################################### Contributing to the documentation ####################################### .. role:: bash(code) :language: bash 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 * :doc:`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: .. code-block:: bash cd CIF_ROOT/docs make html Then, you can simply open html files generated in :bash:`CIF_ROOT/docs/build/html/` in any web browser. It is recommended to re-compile the documentation from scratch time to time: .. code-block:: bash 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 :bash:`index.rst` file in each sub-folders of the documentation. Therein, the file name should be added below the command :bash:`.. 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: :doc:`here `. Automatic construction from codes --------------------------------- The automatic documentation from codes is available :doc:`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 :bash:`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 :bash:`__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 `"""`: .. code-block:: python """ 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 :bash:`..........` to underline sub-titles. * a dictionary :bash:`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 :bash:`"doc"` entry, including a string describing the corresponding argument: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: .. 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: .. code-block:: rst .. 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: .. 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:: yaml 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: .. code-block:: rst .. 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 :bash:`${CIF_ROOT}/docs/source/yaml_examples/chimere/config_fwd_ref_chimere.yml`. The argument :bash:`: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 :bash:`/` For instance, the following example only displays a subset of the :bash:`datavect` paragraph. .. code-block:: rst .. 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: .. yml-block:: /yaml_examples/chimere/config_fwd_ref_chimere.yml :keys: datavect/components/meteo, datavect/components/fluxes, obsoperator, datef, workdir, datei