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.