chore: expose documentation checks locally (#1118)

.github/workflows/docs-antora.yml

@@ -3,12 +3,14 @@ on:
   push:
     paths:
       - 'docs/**'
+      - 'service/internal/config/config.go'
       - 'local-antora-playbook.yml'
       - 'local-antora-playbook-ci.yml'
       - '.github/workflows/docs-antora.yml'
   pull_request:
     paths:
       - 'docs/**'
+      - 'service/internal/config/config.go'
       - 'local-antora-playbook.yml'
       - 'local-antora-playbook-ci.yml'
       - '.github/workflows/docs-antora.yml'

.pre-commit-config.yaml

@@ -33,6 +33,13 @@ repos:
 
   - repo: local
     hooks:
+      - id: docs-check
+        name: docs-check
+        entry: make docs-check
+        language: system
+        pass_filenames: false
+        files: ^(docs/|service/internal/config/config\.go|Makefile)
+
       - id: service-codestyle
         name: service-codestyle
         entry: make service-codestyle

AGENTS.md

@@ -22,6 +22,8 @@ If you are looking for OliveTin's AI policy, you can find it in `AI.md`.
   - From repo root: `cd service && make unittests`
 - Code style (after editing code in `service/`):
   - From repo root: `cd service && make codestyle` (runs `go fmt` and `golangci-lint`; install linter via `make go-tools`)
+- Documentation checks:
+  - From repo root: `make docs-check` (validates documented config key casing and local AsciiDoc anchor links)
 - Integration tests (Mocha + Selenium):
   - All tests: `make it` (from repo root; builds webui + service binary, then runs Mocha)
   - Single test: `cd integration-tests && npx --yes mocha tests/general/general.mjs`

CONTRIBUTING.adoc

@@ -64,6 +64,7 @@ The project layout is reasonably straightforward;
 
 * See the `Makefile` for common targets. This project was originally created on top of Fedora, but it should be usable on Debian/your faveourite distro with minor changes (if any).
 * End-user documentation (AsciiDoc for link:https://docs.olivetin.app[docs.olivetin.app]) lives in `docs/` as an Antora component; the published site is built from the separate link:https://github.com/OliveTin/docs.olivetin.app[docs.olivetin.app] repository.
+* Run `make docs-check` after changing documentation or the service configuration schema.
 * The API is defined in protobuf+Connect RPC - you will need to `make proto`.
 * The Go daemon is built from the `cmd` and `internal` directories mostly.
 * The webui is just a single page application with a bit of Javascript in the `webui` directory. This can happily be hosted on another webserver.

Makefile

@@ -28,6 +28,10 @@ frontend-codestyle:
 frontend-unittests:
 	$(MAKE) -wC frontend unittests
 
+docs-check:
+	python3 docs/modules/ROOT/check_config_keys.py
+	python3 docs/modules/ROOT/check_chevron_links.py
+
 it:
 	$(MAKE) -wC integration-tests
 
@@ -81,4 +85,4 @@ config-tool:
 devcheck:
 	python3 scripts/devcheck.py $(ARGS)
 
-.PHONY: proto default service windows-resources windows-msi frontend-unittests it devcheck
+.PHONY: proto default service windows-resources windows-msi frontend-unittests docs-check it devcheck