Generate a _Sidebar page so the wiki shows its subpages

Task: MIL-005#3

tests/test_build_wiki.py

@@ -1,6 +1,7 @@
 """Offline tests for tools/build_wiki.py."""
 
 import importlib.util
+import re
 from pathlib import Path
 
 import pytest
@@ -154,7 +155,8 @@ class TestWriteAndCheck:
     def test_write_then_check_passes(self, repo, tmp_path):
         wiki = tmp_path / "wiki"
         changed = build_wiki.write_pages(wiki, repo)
-        assert sorted(changed) == sorted(f"{p.name}.md" for p in build_wiki.PAGES)
+        expected = [f"{p.name}.md" for p in build_wiki.PAGES] + [build_wiki.SIDEBAR_NAME]
+        assert sorted(changed) == sorted(expected)
         assert build_wiki.check_pages(wiki, repo) == []
         assert build_wiki.write_pages(wiki, repo) == []
 
@@ -267,3 +269,25 @@ def test_committed_translations_follow_the_english_structure(page, code):
 def test_committed_translations_are_current():
     """No translation follows an older version of its English page."""
     assert build_wiki.check_translations() == []
+
+
+class TestSidebar:
+    """Gitea shows subpages only through _Sidebar, so it must reach every page."""
+
+    def test_links_every_page_in_every_language(self):
+        sidebar = build_wiki.render_sidebar()
+        for page in build_wiki.PAGES:
+            assert f"]({page.name})" in sidebar
+            for code, _label in build_wiki.LANGUAGES:
+                assert f"]({page.name}.{code})" in sidebar
+
+    def test_every_link_names_a_committed_page(self):
+        sidebar = build_wiki.render_sidebar()
+        targets = re.findall(r"\]\(([^)]+)\)", sidebar)
+        assert targets
+        for target in targets:
+            assert (build_wiki.WIKI_DIR / f"{target}.md").is_file(), target
+
+    def test_has_one_label_per_page_and_language(self):
+        for code in ("en", *(c for c, _ in build_wiki.LANGUAGES)):
+            assert len(build_wiki.SIDEBAR_LABELS[code]) == len(build_wiki.PAGES)

tools/build_wiki.py

@@ -184,9 +184,41 @@ def render_page(page: Page, repo_root: Path = REPO_ROOT) -> str:
     return banner + body + "\n"
 
 
+# Link text of the sidebar: English, then one list per translation code.
+SIDEBAR_TITLE = "TirSystem GitHub Actions"
+SIDEBAR_LABELS: dict[str, tuple[str, ...]] = {
+    "en": ("Home", "Onboarding", "Credentials", "Troubleshooting", "Quality checks", "Upgrading", "Capabilities"),
+    "da": ("Hjem", "Tilslutning", "Credentials", "Fejlfinding", "Kvalitetskontrol", "Opgradering", "Kapabiliteter"),
+    "ms": ("Utama", "Menyertakan", "Kelayakan", "Diagnosis", "Semakan kualiti", "Menaik taraf", "Keupayaan"),
+}
+SIDEBAR_NAME = "_Sidebar.md"
+
+
+def render_sidebar() -> str:
+    """Return the navigation shown beside every wiki page.
+
+    Gitea lists subpages only through a ``_Sidebar`` page, so without it a
+    visitor sees the home page and no way to the others.
+    """
+    languages = (("en", "English", ""), *((code, label, f".{code}") for code, label in LANGUAGES))
+    lines = [
+        f"<!-- Generated by {GENERATOR}. Edit the generator, not this page. -->",
+        "",
+        f"**{SIDEBAR_TITLE}**",
+    ]
+    for code, label, suffix in languages:
+        labels = SIDEBAR_LABELS[code]
+        assert len(labels) == len(PAGES), "one sidebar label per page"
+        lines += ["", f"**{label}**", ""]
+        lines += [f"- [{text}]({page.name}{suffix})" for text, page in zip(labels, PAGES)]
+    return chr(10).join(lines) + chr(10)
+
+
 def build_all(repo_root: Path = REPO_ROOT) -> dict[str, str]:
-    """Return ``{file name: content}`` for every English page."""
+    """Return ``{file name: content}`` for every English page and the sidebar."""
-    return {f"{page.name}.md": render_page(page, repo_root) for page in PAGES}
+    pages = {f"{page.name}.md": render_page(page, repo_root) for page in PAGES}
+    pages[SIDEBAR_NAME] = render_sidebar()
+    return pages
 
 
 def write_pages(wiki_dir: Path = WIKI_DIR, repo_root: Path = REPO_ROOT) -> list[str]:

wiki/_Sidebar.md

@@ -0,0 +1,33 @@
+<!-- Generated by tools/build_wiki.py. Edit the generator, not this page. -->
+
+**TirSystem GitHub Actions**
+
+**English**
+
+- [Home](Home)
+- [Onboarding](Onboarding)
+- [Credentials](Credentials)
+- [Troubleshooting](Troubleshooting)
+- [Quality checks](QualityChecks)
+- [Upgrading](Upgrading)
+- [Capabilities](Capabilities)
+
+**Dansk**
+
+- [Hjem](Home.da)
+- [Tilslutning](Onboarding.da)
+- [Credentials](Credentials.da)
+- [Fejlfinding](Troubleshooting.da)
+- [Kvalitetskontrol](QualityChecks.da)
+- [Opgradering](Upgrading.da)
+- [Kapabiliteter](Capabilities.da)
+
+**Bahasa Melayu**
+
+- [Utama](Home.ms)
+- [Menyertakan](Onboarding.ms)
+- [Kelayakan](Credentials.ms)
+- [Diagnosis](Troubleshooting.ms)
+- [Semakan kualiti](QualityChecks.ms)
+- [Menaik taraf](Upgrading.ms)
+- [Keupayaan](Capabilities.ms)