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.
The easiest way to edit our documentation is to use GitHub’s UI editor. Setting up your documentation environment locally is not required.
First, you’ll need to install Python 3.
The easiest way to do this is by installing
This will give you a lightweight Python installation on your machine.
We use the
git command line tool to manage “Version Control” for our repositories, and to keep track of changes.
git locally with the following command:
conda install -c conda-forge git
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.
nox, first confirm you have installed Python then type:
pip install nox
To list all available options to use with
To build documentation locally, run:
nox -s docs
To build documentation with a live server that previews your changes, run:
nox -s docs -- live
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
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
environment.yml. It is sometimes in
Install the environment for the documentation. Manually install the dependencies with
conda. 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.