This file describes how the AMICI documentation is organized and compiled.
The main configuration file is
documentation/conf.py and the documentation
is generated using
scripts/run-sphinx.sh. The documentation is written to
The documentation comprises:
reStructuredText / Markdown files from
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)
(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
The resulting HTML and PDF documentation will be created in
scripts/run-doxygen.sh also checks for any missing in-source documentation.
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 is processed by
This is configured in
Python documentation is processed by doxygen and doxypypy using the script and
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
Graphics for documentation are kept in
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
documentation/references.md. This file is created by
documentation/recreate_reference_list.py based on
the bibtex file
After any changes to
documentation/amici_refs.bib, please run