Documentation generation for BattMo

Requirements

sphinx

installation instruction described here

pip install sphinx

install sphinx rtd theme

https://pypi.org/project/sphinx-rtd-theme/

pip install sphinx-rtd-theme

bibtex extension

https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation

pip install sphinxcontrib-bibtex

globabsubs extension

pip install sphinxcontrib-globalsubs

youtube

pip install sphinxcontrib-youtube

collapse

python -m pip install sphinx_collapse

autosectionlabel

• part of default distribution
• We use autosectionlabel_prefix_document = True which means that the internal link must be prefixed by the file name and a semi-column, see here.

Workflow for editing

In the Documentation directory, run from terminal

make html

The command generates all the files for a static website and writes them in Documentation/_build/html

All the files in this directory must then be copied to the BattMo-doc repo. From there, make a force push. We do not keep track of the history of the ouput files (html), but we of course keep track of the documentation source, directly in the main repo BattMo.

The deployment of the webpage can be followed from the github pages section

The result can be view at

https://battmoteam.github.io/BattMo-doc/

Special workflow for example scripts

Compilation

• run publishExamplesXML in utils directory (see documentation there) : It creates XML outputs
• run python script buildPublishedExamples.py : converts XML to rST output

rST description file

• Matlab uses own markup language which complicates transformation to rST file and therefore it should not be used
• We offer possibility to include extra rST description file automatically. If the example is named myexample.m, then the extra rST file should be named myexamplePreamble.rst

Guidelines

• To make sure that a comment you include in matlab example file appears as a comment in rST output (and not at a comment in the matlab code formatting), start a cell with eventually no title. In Matlab cells start with %% and a title
• The directive .. automodule:: makes sure a directory is parsed.

Interesting Manuals

sphinx manual

https://www.sphinx-doc.org/en/master/contents.html

reStucturedText (rst) format

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

rtd theme manual

https://sphinx-rtd-theme.readthedocs.io/en/stable/

bibtex extension manual

https://sphinxcontrib-bibtex.readthedocs.io/en/latest/index.html

Configuration file

• conf.py see https://www.sphinx-doc.org/en/master/usage/configuration.html