Set up a local documentation environment

To create your documentation environment locally, you’ll need Nox installed. If you wish to build the documentation by-hand without Nox, you’ll also need to install the dependencies for a given repository.

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 and run the documentation engine yourself, you may do so. This differs depending on the repository and which engine it uses. Check the repository’s own README.md and noxfile.py for its exact build command.

For a MyST-based repository (like this one), that usually looks like:

pip install mystmd
myst build --html

See the mystmd documentation for more details.