Developer guide

Build static HTML from the local documentation¶

This project comes with a mini documentation site to demonstrate and preview functionality. This section describes how you can build static HTML files for use in preview services like Netlify.

To build static HTML files with the latest theme changes, you must first build the theme assets, and then serve the site using the theme. The MyST site at docs/ is already configured to use this local theme build (in the .deploy folder), so to use it, run the following commands:

Install the dependencies to build the documentation

This includes both the latest version of MyST, as well as the Python dependencies to run documentation examples. Run the following command to do so:

pip install -r docs/requirements.txt

Then, build the latest version of the theme and preview the local documentation with it

make build-book
cd docs
myst build --execute --html

This will output HTML files for the documentation in docs/_build/html that you can re-use elsewhere.

You can also run this with the Make comment:

make build-docs

Previews in Pull Requests¶

We use Netlify to build the latest version of this theme from Pull Requests, and provide a preview. Ask one of the team members if you need access to its configuration.