Set up the documentation repository

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

Initial setup

If you’re starting a new project, clone the starter pack repository and begin your project from there.

If you already have a project, download the following files locally and copy them into your existing repository:

  • 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

Then, 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.

Pre-commit hooks (optional)

Use pre-commit hooks with the starter pack to automate checks like spelling and inclusive language.

The starter pack includes a ready-to-use .pre-commit-config.yaml file under docs/.sphinx/:

repos:
  - repo: local
    hooks:
      - id: make-spelling
        name: Run make spelling
        entry: make -C docs spelling
        language: system
        pass_filenames: false

      - id: make-linkcheck
        name: Run make linkcheck
        entry: make -C docs linkcheck
        language: system
        pass_filenames: false

      - id: make-woke
        name: Run make woke
        entry: make -C docs woke
        language: system
        pass_filenames: false

For a new project, copy this file to your project’s root directory; for an existing project using pre-commit, add these hooks to your configuration.

To apply the configuration, install the starter pack hooks, for instance:

pre-commit install --config docs/.sphinx/.pre-commit-config.yaml

After that, you should see the checks running with every commit:

git commit -m 'add spelling errors'

Run make spelling.......................................................Failed
Run make linkcheck......................................................Passed
Run make woke...........................................................Passed