How to build documentation locally

Note

This page was written in the style of a How-to Guide according to The Diátaxis Framework.

This guide shows how to build the documentation of your project in a local machine.

Pre-requisites

This guide assumes your project already has a working Sphinx documentation project in a folder called docs. If you don’t have it, you can set it up with sphinx-quickstart.

Install package and dependencies

Before trying to build your documentation, make sure you have installed:

  • The project you want to build, that in this guide will be called qiskit_x.

  • Other required packages from the corresponding requirements-dev.txt.

Install the Qiskit package

Once you have cloned the qiskit-x repository with git clone https://github.com/<your user/organization_name/qiskit-x.git, you can install the qiskit_x package from source by going to the root directory of your local copy and running this on your console:

pip install .

If you prefer to install the editable version, so you don’t have to reinstall each time the code from the project is changed, you can write:

pip install -e .

Install required packages

Apart from installing the qiskit_x package, there are other needed packages for development. They are included in the requirements-dev.txt files of the repository. You can install the packages from those files with:

pip install -r requirements-dev.txt

However, there can also be some other necessary packages that are not Python, and therefore not installable with pip, like pandoc or graphviz. You can install them with apt-get install:

sudo apt-get install other_packages

Build the documentation

Once you have installed every needed package in your virtual environment, you can build the documentation with sphinx-build the following way:

sphinx-build -b html docs docs/_build/html

After that, the documentation you have built from the docs folder will be in docs/_build/html.

Shortcuts

There are also some shortcuts for all or part of this process that can be made by modifying certain files. This guide will focus on the full process but you can remove any lines you don’t want to automatice. This shortcuts are:

  • make html

  • tox -edocs

make html

In order to build your documentation with make html you need to include the following lines in your Makefile.

html:
    pip install -r requirements-dev.txt
    sudo apt-get install -y other_packages
    sphinx-build -b html docs docs/_build

tox -edocs

If you want to use tox -edocs to build your documentation with tox, you can include the following in your tox.ini file:

[testenv:docs]
envdir = .tox/docs
basepython = python3
deps =
    -r{toxinidir}/requirements-dev.txt
    other_dependencies
commands =
    sphinx-build -b html {posargs} {toxinidir}/docs {toxinidir}/docs/_build/html

the variable toxinidir is the path to your tox.ini, that should be in the root directory of your repository.