Documentation

Several parts of ARTS generate automatic documentation.

This document describes some of these automatic document generators.

This is an incomplete document.

Examples folder

The documentation for the Examples tab is generated from the structure and layout of the files in the examples/ directory. The code responsible for this is the python/doc/gen_examples.py script.

There are several complicated rules involved in the generation of the documentation. The basic idea is that every rst, py, and ipynb file in the examples/ directory is considered a documentation file and will some how.

Note

The py and ipynb files are also considered tests and will run during the CI.

Here is a short list of rules and some explanations for why they exist:

  1. The name of the folder is used as the title of the documentation page. We want a 1-to-1 translation so that the examples are easy to find. Capitalization of the title is done automatically for the first letter. The rest of the title is kept as is.

  2. The sorting of all the content is alphanumerical. Put 1*, 2*, etc., in front of the filenames to control the order if oyu think it matters.

    1. Using N- leaves the numbering in the title and TOC. Using N. does not and removes the number. The ordering remains alphanumerical, with 1. before 2-, and so on, so local consistency is important.

    2. If an rst files has the same stem name as a py file, the rst file is reordered before the py file. This is to allow ex.rst to contain a description of the ex.py file to be displayed.

    3. The file README.rst is always put first in the folder regardless of other names so that we can introduce the topics covered.

  3. The rst files are copied as are.

  4. The py files are put into sphinx code-blocks.

  5. The ipynb files are copied and run using a Sphinx extension called nbsphinx. The execution of the notebook means that it will appear on the webpage as it does after local execution.

    Note

    We only allow one ipynb file per folder. We do not know how nbsphinx can be used to support multiple notebooks in the same folder. If this is fixed, this policy will be changed.

  6. When multiple py files or rst files are present in a folder, their names will be used as subtitles in the documentation.

    1. The README.rst file does not get a subtitle. Please generate any of its subtitles in the file itself.

  7. The main title level in the generated documents is the ==== level and subtitles are ----. See the Sphinx documentation on header levels for more information. Please remain consistent with these levels in you files to avoid a confusing layout in the generated documentation.

The Workspace documentation

The Workspace tab is generated by wrapping automatically generateddocumentation for the workspace variables, methods, agendas, and groups. These automatic documentation are generated by python/doc/gen_overview_list.py, which simply creates a .. hlist::-list of all the above. In turn, there are special rules for how to document each of the workspace variables, methods, agendas, and groups. These rules are:

  1. The builtin documentation is generated by one of

    1. src/python_bindings/gen_auto_py_groups.cpp

    2. src/python_bindings/gen_auto_py_variables.cpp

    3. src/python_bindings/gen_auto_py_methods.cpp

    For purposes of documentation, enumerations are considered workspace groups, and agendas are considered workspace variables. This follows from how they are bound in the C++ code.

  2. Several C++-files contain raw text that will be included in the generated documentation in one way or another. These files and what they represent are:

    1. src/workspace_groups.cc - contains the pure workspace groups’ documentation. Also generates agenda operators as part of the process.

    2. src/workspace_variables.cc - contains named workspace variables’ documentation. This includes the generated agenda variables.

    3. src/workspace_methods.cc - contain pure workspace methods’ documentation. Also generates several methods based on agendas and meta methods.

    4. src/workspace_meta_methods.cc - contain workspace methods’ documentation that composed by calling other methods.

    5. src/workspace_method_extra_doc.cc - contains extra documentation for workspace methods when this must be generated at a later stage, when other generated information is available. For instance, for things like selection methods that are called by a combination of various pre-selected options. Do not use this file unless you know what you are doing. Do use it for options-combining tasks though.

    6. src/workspace_agendas.cc - contains workspace agendas’ documentation. This includes contraints that are both documentation and executed code by verbatim copy-pasting, so be careful.

    7. src/core/options/arts_options.cc - contains the documentation for the ARTS options that are used to configure various parts of ARTS. These workspace groups but they will generate documentation based on the information within this file.

    8. Every file in src/python_interface/py_*.cpp that contains a raw string. Every class and method defined in these files must have a docstring, and that docstring will verbatim be used in the generated documentation.

    The text in these files is used as the builtin documentation for the workspace items, and it is also used to generate the parameter lists for methods and agendas.

    Note

    We have a special rule for the raw strings in all the files except those at src/python_interface/py_*.cpp. The * character is reserved. It can only be used to generate **bold** text, or to create a *link* to an existing workspace item. You cannot generate *italics* text in these files. If you need italics, use emphasis:.

  3. Only workspace groups document any information beyond the python-visible (via item?) builtin documentation. This is because the groups have special bindings in python that makes it necessary to not just document the interface and relationships, but also the methods and attributes that are available for the group.

    1. The additional information is a table view of all the groups’ public methods (static and non-static), attributes, and a selection of double-underscore methods, like __getitem__ and __setitem__, among others. See python/doc/gen_pyarts_arts_autoclass_rst.py and expand it for the choosen double-underscore methods.

    2. This table view is followed by an .. automethod:: or .. autoattribute Sphinx directive for the appropriate content.

  4. Workspace methods, agendas, and operators are documented with their parameter lists. The parameter lists show in bold text whether the parameter is an output ([OUT]) an input ([IN]), or both ([INOUT]).

  5. Workspace methods’ builtin documention states whether or not they are used by a meta method. Meta methods in turn document which methods they use and in what order.

  6. Workspace variables’ builtin documentation states which methods and agendas create, modify, or use the variable. Additionally, they document which other workspace variables are related to the variable. A variable is related to another variable if

    1. Any part of the related variable’s name equals the name of the variable plus some separator. Example: a is related to a_b.

    2. Any part of the variable match a keyword. If it does, all other variables that match the same keyword are considered related to the variable. The keywords are defined in the src/workspace_variables_keywords.cc file.