AMICI documentation

This file describes how the AMICI documentation is organized and compiled.

Building documentation

Multi-interface documentation

AMICI documentation hosted at Read the Docs (RTD) is generated using Sphinx and related packages. The legacy GitHub Pages URL https://amici-dev.github.io/AMICI/ is set up as a redirect to RTD.

The main configuration file is documentation/conf.py and the documentation is generated using scripts/run-sphinx.sh. The documentation is written to documentation/_build/.

The documentation comprises:

  • reStructuredText / Markdown files from documentation/

  • Python API documentation of native Python modules

  • Python API documentation of Python generated via SWIG (doxygen-style comments translated to docstrings by SWIG)

  • C++ API documentation (doxygen -> exhale -> breathe -> sphinx)

  • Matlab API documentation (mtocpp -> doxygen -> exhale -> breathe -> sphinx)

Doxygen-only (legacy)

(Parts of the) AMICI documentation can also be directly created using doxygen directly. It combines Markdown files from the root directory, from documentation/ and in-source documentation from the C++ and Matlab source files.

The documentation is generated by running

scripts/run-doxygen.sh

The resulting HTML and PDF documentation will be created in doc/. scripts/run-doxygen.sh also checks for any missing in-source documentation.

Doxygen configuration

The main doxygen configuration file is located in matlab/mtoc/config/Doxyfile.template. Edit this file for inclusion or exclusion of additional files.

Matlab documentation

Matlab documentation is processed by mtoc++. This is configured in matlab/mtoc/config.

Python documentation

Python documentation is processed by doxygen and doxypypy using the script and filters in scripts/.

Writing documentation

Out-of-source documentation

Out-of-source documentation files should be written in reStructuredText if intended for Read the Docs or in Markdown if intended for rendering on GitHub. Files to be included in the Sphinx/RTD documentation live in documentation/. Graphics for documentation are kept in documentation/gfx/.

When using Markdown

  • Note that there are some incompatibilities of Github Markdown and Doxygen Markdown. Ideally documentation should be written in a format compatible with both. This affects for example images links which currently cause trouble in Doxygen.

  • Where possible, relative links are preferred over absolute links. However, they should work with both Github and Doxygen and ideally with local files for offline use.

  • Please stick to the limit of 80 characters per line for readability of raw Markdown files where possible.

    However, note that some Markdown interpreters can handle line breaks within links and headings, whereas others cannot. Here, compatibility is preferred over linebreaks.

  • Avoid trailing whitespace

Maintaining the list of publications

We want to maintain a list of publications / projects using AMICI. This is located at documentation/references.md. This file is created by documentation/recreate_reference_list.py based on the bibtex file documentation/amici_refs.bib.

After any changes to documentation/amici_refs.bib, please run

documentation/recreate_reference_list.py

(requires biblib)