Documentation Standards

MDMC follows the NumPy documentation style, which is consistent with PEP 257. The exceptions to this are:

The Attributes section should be the last section in a class docstring. This is because Sphinx formats Attributes in the same manner to methods (without a heading), so it leads on to this.
Properties should not be documented in the Attributes section, as then they are duplicated in Sphinx. Instead they should only be documented in the getter method. As long as properties precede methods, the properties will follow the attributes in the Sphinx documentation.
Parameters that can only assume one of a fixed set of values, in NumPy these values are listed instead of the type. This is not the case in MDMC as at this early development stage these values are still in flux. Therefore instead just state the type:

"""
Parameters
----------
MDMC : str
    This is how MDMC does it.
NumPy : {'C', 'F', 'A'}
    This is how NumPy does it.
"""

Sphinx

To build the documentation using Sphinx, pandoc must be installed. This is not the same as the pandoc which is available from pypi (e.g. which is installed using pip install pandoc ).
All images should be included in doc/_static/images
All .ipynb tutorials should be included in doc/tutorials. When modifying these tutorials, jupyter notebook must be run from the doc directory, not the tutorials directory. This is because the Jupyter server then has access to the _static/images folder, which is required for some tutorials.

Adding to documentation

Currently, MDMC uses Github Actions to deploy documentation to the website, MDMCproject.org. This means to add to the documentation, do not directly merge or pull request to the MDMCproject.github.io repository. Rather, make your changes to the .rst files in the main source code’s ‘doc’ folder, and then once they have been merged a cron job will deploy them to the website every Sunday evening.