Contributing to the documentation

Local documentation

The documentation of MAICoS is written in reStructuredText (rst) and uses the Sphinx documentation generator. You can build the documentation from the maicos/docs folder:

tox -e docs

Then, visualize the local documentation with your favorite internet explorer (here Mozilla Firefox is used)

firefox docs/build/html/index.html

Structure

Most of the content of the documentation is written in .rst files located within docs/src/. The content in the API documentation section is directly generated from the documentation string of the source code located in src/maicos thanks to Sphinx and Autodoc.

After creating a new module, add it to the documentation by modifying the toctree in the docs/src/references/modules/index.rst file, and adding a new .rst file with the following format:

.. _ModuleName:

ModuleName
##########

.. _label_module_name:

.. autoclass:: maicos.ModuleName
    :members:
    :undoc-members:
    :show-inheritance:

Note that all files located within docs/src/examples are generated from the Python scrips located in examples using Sphinx-Gallery.