Skip to content

Files

Latest commit

 

History

History
 
 

documentation

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
_templates/autosummary
_templates/autosummary
 
 
gfx
gfx
 
 
CI.md
CI.md
 
 
CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
CPP.rst
CPP.rst
 
 
CPP_.md
CPP_.md
 
 
ExampleEquilibrationLogic.ipynb
ExampleEquilibrationLogic.ipynb
 
 
ExampleExperimentalConditions.ipynb
ExampleExperimentalConditions.ipynb
 
 
ExampleJax.ipynb
ExampleJax.ipynb
 
 
ExampleJaxPEtab.ipynb
ExampleJaxPEtab.ipynb
 
 
ExampleSplines.ipynb
ExampleSplines.ipynb
 
 
ExampleSplinesSwameye2003.ipynb
ExampleSplinesSwameye2003.ipynb
 
 
ExampleSteadystate.ipynb
ExampleSteadystate.ipynb
 
 
GettingStarted.ipynb
GettingStarted.ipynb
 
 
LICENSE.md
LICENSE.md
 
 
MATLAB.rst
MATLAB.rst
 
 
MATLAB_.md
MATLAB_.md
 
 
PYTHON.rst
PYTHON.rst
 
 
README.md
README.md
 
 
about.rst
about.rst
 
 
amici_refs.bib
amici_refs.bib
 
 
availability.rst
availability.rst
 
 
background.rst
background.rst
 
 
changelog.md
changelog.md
 
 
code_review_guide.md
code_review_guide.md
 
 
conf.py
conf.py
 
 
contributing.rst
contributing.rst
 
 
cpp_installation.rst
cpp_installation.rst
 
 
cpp_interface.rst
cpp_interface.rst
 
 
debugging.rst
debugging.rst
 
 
development.rst
development.rst
 
 
example_errors.ipynb
example_errors.ipynb
 
 
example_large_models
example_large_models
 
 
glossary.rst
glossary.rst
 
 
how_to_cite.rst
how_to_cite.rst
 
 
implementation_discontinuities.rst
implementation_discontinuities.rst
 
 
index.rst
index.rst
 
 
matlab_faq.rst
matlab_faq.rst
 
 
matlab_installation.rst
matlab_installation.rst
 
 
matlab_interface.rst
matlab_interface.rst
 
 
model_steadystate_scaled.xml
model_steadystate_scaled.xml
 
 
model_steadystate_scaled_without_observables.xml
model_steadystate_scaled_without_observables.xml
 
 
petab.ipynb
petab.ipynb
 
 
python_examples.rst
python_examples.rst
 
 
python_faq.rst
python_faq.rst
 
 
python_installation.rst
python_installation.rst
 
 
python_interface.rst
python_interface.rst
 
 
python_modules.rst
python_modules.rst
 
 
recreate_reference_list.py
recreate_reference_list.py
 
 
references.md
references.md
 
 
rtd_requirements.txt
rtd_requirements.txt
 
 
versioning_policy.rst
versioning_policy.rst
 
 

README.md

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 tox -e doc. 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.

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)