Update this documentation

📜 If you think it can be clearer, or you want to add more details or tutorials …

Generating local docs

First you need a few dependencies (besides those for qmat). For that download the source code and install the package with all the docs dependencies locally :

git clone https://github.com/Parallel-in-Time/qmat.git
cd qmat
pip install -e .[docs]  # on MAC-OS : pip install -e ".[docs]"

📜 The -e option ensures that your installed python package is directly linked to the sources (no copy of code), hence modifying any part of the source code (in particular the documentation) will be taken into account when sphinx will parse the code docstring.

Then to generate the documentation website locally, simply run :

cd docs
make html

This builds the sphinx documentation automatically in a _build folder, and you can view it by opening docs/_build/html/index.html using your favorite browser.

Updating a tutorial

When changing a notebook tutorial, you should also regenerate it entirely, in particular if you modified parts of the code. You can do that by running :

cd notebooks
./run.sh $NOTEBOOK_FILE

If you modified several notebooks, and as a safety, it is also possible to regenerate all doing :

./run.sh --all

📣 When modifying only the markdown text in a notebooks, it is not necessary to regenerate it.

Adding a tutorial

Feel free to add new notebooks in the “Advanced Tutorial” section, for a specific application that is not covered by the current tutorials. Just name the notebook like this : 2{idx}_{shortName}.ipynb when idx corresponds to its index in category (starts at 1), and use the Tuto A{idx} prefix for the notebook title.

💡 Don’t hesitate to look at the other notebooks to use a common and consistent formatting …