# 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)](https://amici.readthedocs.io/) is
generated using [Sphinx](https://www.sphinx-doc.org/) and related packages.
The legacy GitHub Pages URL https://amici-dev.github.io/AMICI/ is set up as a
redirect to RTD.

The sphinx configuration file is `doc/conf.py` and the documentation
is generated using `tox -e doc`. The documentation is written to
`doc/_build/`.

The documentation comprises:

* reStructuredText / Markdown files from `doc/`
* 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)

### Doxygen-only (legacy)

(Parts of the) AMICI documentation can also be directly created using
[doxygen](http://www.doxygen.nl/) directly. It combines Markdown files from
`doc/` and in-source documentation from the C++ source files.

The documentation is generated by running

    scripts/run-doxygen.sh

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

#### Doxygen configuration

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

## 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 `doc/`.
Graphics for documentation are kept in `doc/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, image 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 `doc/references.md`. This file is created by
`doc/recreate_reference_list.py` based on
the bibtex file `doc/amici_refs.bib`.

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

    documentation/recreate_reference_list.py

(requires [biblib](https://github.com/aclements/biblib))