ARCHIVED SINCE 2021-05-01
The documentation is now hosted in the
doc folder of the qutip/qutip repository.
As of May 2021, this is no longer the main repository for QuTiP documentation development, but is preserved to avoid breaking old links. Please submit all new issues and pull requests there, instead.
The rest of this readme and repository are left as-is.
Repository for QuTiP documentation
This repository contains the source files for the QuTiP documentation.
For pre-built documentation, see http://www.qutip.org/documentation.html
The main Python requirements for the documentation are
You should build or install the version of QuTiP you want to build the documentation against in the same environment.
You will also need a sensible copy of
make, and if you want to build the LaTeX documentation then also a
As of 2021-04-20, the
conda recipe for
sphinx_rtd_theme is rather old compared to the
pip version, so it's recommended to use a mostly
pip-managed environment to do the documentation build.
The simplest way to get a functional build environment is to use the
requirements.txt file in this repository, which completely defines a known-good
pip environment (tested on Python 3.8, but not necessarily limited to it).
If you typically use conda, the way to do this is
$ conda create -n qutip-doc-build python=3.8 $ conda activate qutip-doc-build $ pip install -r /path/to/qutip-doc/requirements.txt
You will also need to build or install the main QuTiP library in the same environment.
If you simply want to build the documentation without editing the main library, you can install a release version of QuTiP with
pip install qutip.
Otherwise, refer to the main repository for the current process to build from source.
You need to have the optional QuTiP dependency
Cython to build the documentation, but this is included in this repository's
requirements.txt so you do not need to do anything separately.
After you have done this, you can effect the build with
The targets you might want are
clean, which build the HTML pages, build the PDFs, and delete all built files respectively.
For example, to build the HTML files only, use
$ make html
Note (2021-04-20): the documentation build is currently broken on Windows due to incompatibilities in the main library in multiprocessing components.
Writing User Guides
The user guide provides an overview of QuTiP's functionality. The guide is composed of individual reStructuredText (
.rst) files which each get rendered as a webpage. Each page typically tackles one area of functionality. To learn more about how to write
.rst files, it is useful to follow the Sphinx Guide.
The documentation build also utilizes a number of Sphinx Extensions including but not limited to
doctest , autodoc , sphinx gallery , plot . Additional extensions can be configured in the
Tests can also be run on examples in the documentation using the doctest extension
and plots are generated using the
plot directive. For more specific
guidelines on how to incorporate code examples into the guide, refer to (insert reference).