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