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 :doc:`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. a. 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. b. 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. c. 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. a. 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 :doc:`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 a. ``src/python_bindings/gen_auto_py_groups.cpp`` b. ``src/python_bindings/gen_auto_py_variables.cpp`` c. ``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: a. ``src/workspace_groups.cc`` - contains the pure workspace groups' documentation. Also generates agenda operators as part of the process. b. ``src/workspace_variables.cc`` - contains named workspace variables' documentation. This includes the generated agenda variables. c. ``src/workspace_methods.cc`` - contain pure workspace methods' documentation. Also generates several methods based on agendas and meta methods. d. ``src/workspace_meta_methods.cc`` - contain workspace methods' documentation that composed by calling other methods. e. ``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. f. ``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. g. ``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. h. 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. a. 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. b. 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 a. Any part of the related variable's name equals the name of the variable plus some separator. Example: ``a`` is related to ``a_b``. b. 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.