Add pre-commit file

.github/workflows/lint.yml

@@ -0,0 +1,39 @@
+name: Check RST file syntax
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  # Run "pre-commit run --all-files"
+  pre-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+
+      # ref: https://github.com/pre-commit/action
+      - uses: pre-commit/[email protected]
+      - name: Help message if pre-commit fail
+        if: ${{ failure() }}
+        run: |
+          echo "You can install pre-commit hooks to automatically run formatting"
+          echo "on each commit with:"
+          echo "    pre-commit install"
+          echo "or you can run by hand on staged files with"
+          echo "    pre-commit run"
+          echo "or after-the-fact on already committed files with"
+          echo "    pre-commit run --all-files --hook-stage manual"
+
+  sphinx-build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+      - run:  pip install sphinx
+      - run:  cd source && sphinx-build -b html . html index.rst

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: check-case-conflict
+  - id: check-executables-have-shebangs
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-merge-conflict
+  #- id: end-of-file-fixer
+  #- id: check-json
+
+# We use the Python version instead of the original version which seems to require Docker
+# https://github.com/koalaman/shellcheck-precommit
+- repo: https://github.com/shellcheck-py/shellcheck-py
+  rev: v0.9.0.6
+  hooks:
+    - id: shellcheck
+      name: shellcheck
+      args: ["--severity=error"]
+      stages: [manual]
+
+- repo: https://github.com/rstcheck/rstcheck
+  rev: v6.2.0
+  hooks:
+  - id: rstcheck
+    additional_dependencies: [sphinx]
+    args: ["--ignore-languages=c,python,java", "--report-level=error"]
+    stages: [manual]
+
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.26.3
+  hooks:
+    - id: check-github-workflows
+
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: "v1.10.0"
+  hooks:
+    # - id: rst-backticks
+    - id: rst-directive-colons
+    - id: rst-inline-touching-normal
+
+# - repo: https://github.com/codespell-project/codespell
+#   rev: "v2.2.6"
+#   hooks:
+#   - id: codespell
+#     exclude_types: [json,yaml]

README.rst

@@ -112,6 +112,26 @@ Store all source documents in the ``source/`` directory.
 
 .. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
 
+Linting
+-------
+
+This repo uses `pre-commit <https://pypi.org/project/pre-commit/>`_
+for managing linting.
+``pre-commit`` performs various checks on the files and uses tools
+that help follow a consistent style within the repo.
+
+To set up ``pre-commit`` locally, run:
+
+.. code:: bash
+    pip install pre-commit  # or brew install pre-commit
+    pre-commit install
+To run ``pre-commit`` manually, run ``pre-commit run --all-files``.
+
+To run a manual hook like ``rstcheck`` manually, run:
+
+.. code:: bash
+    pre-commit run --all-files --hook-stage manual rstcheck
+
 Prose test numbering
 --------------------