Set up the documentation repository

This page contains a short guide on how to set up and use the starter pack.

Initial setup

Clone the Starter pack repository to a local folder.

Assuming that you have an existing repository that you want to build documentation in, you’ll need to copy some files to it. Copy:

• the entire docs directory

• .readthedocs.yaml (configuration for the building on Read the Docs)

• .wokeignore (configuration for the Woke tool)

• the entire .github/workflows directory

You must delete .github/workflows/test-starter-pack.yml.

Build and run the local server

Building the documentation requires make, python3, python3-venv, python3-pip.

In docs, run:

make run

This creates and activates a virtual environment in docs/.sphinx/venv, builds the documentation and serves it at http://127.0.0.1:8000/.

The server watches the source files, including docs/conf.py, and rebuilds automatically on changes.

The landing page is docs/index.rst. Other pages are under docs/content.

Configure settings

Work through the settings in docs/conf.py. Most parameters can be left with the default values as they can be changed later. Customise the setup contains further guidance.