Documentation generation for BattMo

Requirements

Installation

Run from the Documentation directory where the requirements.txt file is

pip install -r requirements.txt

Overview of the package used in sphinx

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

When the changes are pushed, the documentation is also automatically compiled on github using github actions

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

The result can be view at

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

Workflow for notebooks written in mlx format

Compilation

We use the export function from matlab to export the notebook to ipynb format. An help exporter class is provided here. The following script gives example on how it can be used. I have noticed problems with older Matlab version. Please update to R24b.

Output

direct

Write the output in the Documentation directory. At the moment, the notebooks are located in the directory pynbnotebooks

link using nbsphinx-link

• We use nbsphinx-link
• Create a link file with extension nblink, see example here
• insert link in index, see example runThermalExample.nblink in here (line 16)

Include in the index or in pages

See example to the tutorial pages here

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. Include only one white-space betwen % sign and text (otherwise publish routine exports differently).
• 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