add pre-commit configuration and steps

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+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

docs/.sphinx/requirements.txt

@@ -1,4 +1,5 @@
 canonical-sphinx[full]
+pre-commit
 sphinx-autobuild
 sphinxcontrib-svg2pdfconverter[CairoSVG]
 sphinx-last-updated-by-git

docs/content/set-up.rst

@@ -17,7 +17,7 @@ If you already have a project, download the following files locally and copy the
 * the entire :file:`docs` directory
 * :file:`.readthedocs.yaml` (configuration for the building on Read the Docs)
 * :file:`.wokeignore` (configuration for the Woke tool)
-* the entire :file:`.github/workflows` directory 
+* the entire :file:`.github/workflows` directory
 
 Then, you **must** delete :file:`.github/workflows/test-starter-pack.yml`.
 
@@ -42,3 +42,32 @@ Configure settings
 ==================
 
 Work through the settings in :file:`docs/conf.py`. Most parameters can be left with the default values as they can be changed later. :ref:`customise` contains further guidance.
+
+
+Pre-commit hooks (optional)
+===========================
+
+Use `pre-commit <https://pre-commit.com/>`_ hooks with the starter pack
+to automate checks like spelling and inclusive language.
+
+The starter pack includes a ready-to-use :file:`.pre-commit-config.yaml` file:
+
+.. literalinclude:: ../../.pre-commit-config.yaml
+   :language: yaml
+
+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::
+
+  pre-commit install
+
+
+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