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:

  1. 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 or environment.yml. It is sometimes in docs/requirements.txt.

  2. Install the environment for the documentation. Manually install the dependencies with pip or conda. For example:

    pip install -r requirements.txt
    
  3. 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.