Set up a local documentation environment#
To create your documentation environment locally, you’ll need a Python environment as well as Nox installed. If you wish to build Sphinx by-hand without Nox, you’ll also need to install the dependencies for a given repository.
Note
The easiest way to edit our documentation is to use GitHub’s UI editor. Setting up your documentation environment locally is not required.
Install Python#
First, you’ll need to install Python 3.
The easiest way to do this is by installing miniconda
.
This will give you a lightweight Python installation on your machine.
Install git
#
We use the git
command line tool to manage “Version Control” for our repositories, and to keep track of changes.
Install git
locally with the following command:
conda install -c conda-forge git
Install nox
#
Most of our documentation is buildable with the nox
automation tool.
This is a lightway way to execute commands in an isolated environment.
It will let you both install the dependencies for your documentation and build it with a single command.
To install nox
, first confirm you have installed Python then type:
pip install nox
To list all available options to use with nox
, run:
nox -l
To build documentation locally, run:
nox -s docs
To build documentation with a live server that previews your changes, run:
nox -s docs -- live
Clear the nox
environment cache#
When you run a job with nox
, it will automatically install the necessary dependencies for you and place them in a local folder called .nox
.
This is folder is usually hidden, and it contains all of the files needed to run a Nox build.
To delete the environment and force Nox to re-install things from scratch, deleted this folder.
For example, on *nix
platforms, run:
rm -rf .nox
Manually install the environment for documentation#
Normally, Nox will handle all of the environment installation for you. However if you prefer to install the environment manually and runs Sphinx yourself, you may do so. This differs slightly depending on the repository, but it usually works like this:
Find the environment files for the repository documentation. These define the dependencies needed to build the documentation. It is usually in a file called
requirements.txt
orenvironment.yml
. It is sometimes indocs/requirements.txt
.Install the environment for the documentation. Manually install the dependencies with
pip
orconda
. For example:pip install -r requirements.txt
Build the documentation with Sphinx. Finally, you can build the documentation locally with Sphinx using a command like so:
sphinx-build -b dirhtml docs docs/_build/dirhtml
See the Sphinx documentation for more details.