Set up the documentation repository

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

Copy the starter pack

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

If you’re adding documentation to an existing software project, copy the following files from the starter pack repository into your project:

  • 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

Remove the unneeded files

Next, review the starter pack files and remove those that could interfere with your project.

Remove the files that can’t be reused:

  • .github/CODEOWNERS

  • .github/workflows/test-starter-pack.yml

Review and remove the GitHub workflows in .github/workflows/ that your project might not need:

  • sphinx-python-dependency-build-checks.yml verifies Python dependencies for the documentation system. If your project has its own dependency checks, it won’t need this workflow.

  • markdown-style-checks.yml runs the built-in Markdown linter. If your project already validates its Markdown files, it won’t need this workflow.

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 one of the sub-directories under docs/.

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
        files: ^docs/.*\.(rst|md|txt)$

      - id: make-linkcheck
        name: Run make linkcheck
        entry: make -C docs linkcheck
        language: system
        pass_filenames: false
        files: ^docs/.*\.(rst|md|txt)$

      - id: make-woke
        name: Run make woke
        entry: make -C docs woke
        language: system
        pass_filenames: false
        files: ^docs/.*\.(rst|md|txt)$

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