Tarski - Documentation

We currently use a mixture of reStructuredText, markdown and Jupyter notebooks for our documentation. Everything under this docs directory is automatically built on the https://readthedocs.org/ servers on every push to the main branches of the repo. The main docs are served under https://tarski.readthedocs.io/en/latest/, while the docs for the devel branch, for instance, are served under https://tarski.readthedocs.io/en/devel/.

Readthedocs thus parses the whole docs directory and generated the documentation through the Sphinx generator. If you need to fine-tune some readthedocs options through their web interface, you’ll need to create a user at https://readthedocs.org/ and ask Guillem to add you to the list of people with “maintainer” rights.

In any case, the file conf.py contains our specific Sphinx setup, which includes, among others, instructions to load plugins that enable the parsing and rendering of markdown and even the execution of Jupyter notebooks.

Building the docs locally

You should be able to generate the docs locally by a similar procedure than the one used by readthedocs. For this, you need to install the docs Tarski specified in setup.py, e.g. by running:

pip install -e .[docs]

And then you should be able to bootstrap Sphinx by running from the docs directory:

make html

The generated docs are left in _build/html/index.html