Generate categorical pages

Author: manics

.github/workflows/workflow.yml

@@ -33,6 +33,6 @@ jobs:
 
       - name: Build docs
         run: |
-          mkdocs build --strict
+          make build
 
       # TODO: Internal link check

.readthedocs.yaml

@@ -6,6 +6,9 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3"
+  jobs:
+    pre_build:
+      - make pre-build
 
 mkdocs:
   configuration: mkdocs.yml

Makefile

@@ -0,0 +1,14 @@
+
+pre-build:
+	python ./plugins/create_category_pages.py
+
+build: pre-build
+	mkdocs build --strict
+
+serve: pre-build
+	mkdocs serve
+
+.PHONY: clean
+clean:
+	rm -f docs/categories/*
+	rm -rf site/*

docs/categories/.gitignore

@@ -0,0 +1 @@
+*

plugins/create_category_pages.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+from pathlib import Path
+import re
+import yaml
+
+
+def _slugify(s: str):
+    return re.sub(r"\W", "-", s.lower())
+
+ROOT = Path(__file__).parent / ".."
+
+TEMPLATE = """
+# %CATEGORY%
+
+{{ read_yaml("uktre-glossary.yaml", record_path="glossary", category="%CATEGORY%") }}
+"""
+
+with open(ROOT / "assets" / "uktre-glossary.yaml") as f:
+    data = yaml.safe_load(f)
+categories = set(t for term in data["glossary"] for t in term["tags"])
+
+# Check categories don't have inconsistent names
+slugs = {}
+for category in categories:
+    slug = _slugify(category)
+    if slug in slugs:
+        raise ValueError(f"Category has inconsistent naming: '{slugs[slug]}' '{category}'")
+    slugs[slug] = category
+
+for slug, category in sorted(slugs.items()):
+    print(f"{category:<40} {slug}")
+    with open(ROOT / "docs" / "categories" / f"{slug}.md", "w") as f:
+      f.write(TEMPLATE.replace("%CATEGORY%", category))