Version documentation index and contracts

tests/test_docs_versioning.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Docs versioning checks for operator-facing references."""
+import json
+import re
+import tomllib
+import unittest
+from pathlib import Path
+
+from enodia_sentinel import __version__
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS = ROOT / "docs"
+
+
+class TestDocsVersioning(unittest.TestCase):
+    def test_docs_version_matches_package_metadata(self):
+        pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
+        package_version = pyproject["project"]["version"]
+        docs_version = json.loads((DOCS / "VERSION.json").read_text())
+
+        self.assertEqual(package_version, __version__)
+        self.assertEqual(docs_version["project"], "enodia-sentinel")
+        self.assertEqual(docs_version["package_version"], package_version)
+        self.assertEqual(docs_version["docs_version"], ".".join(package_version.split(".")[:2]))
+        self.assertEqual(docs_version["schema_generation"], "v1")
+        self.assertEqual(docs_version["command_reference"], "docs/COMMAND_REFERENCE.md")
+        self.assertEqual(docs_version["schema_reference"], "docs/SCHEMAS.md")
+
+    def test_versioned_docs_headers_are_present(self):
+        version = json.loads((DOCS / "VERSION.json").read_text())
+        for name in ("INDEX.md", "COMMAND_REFERENCE.md", "SCHEMAS.md"):
+            with self.subTest(name=name):
+                text = (DOCS / name).read_text()
+                self.assertIn(
+                    f"Applies to package version: `{version['package_version']}`",
+                    text,
+                )
+                self.assertIn(f"Docs version: `{version['docs_version']}`", text)
+                self.assertIn(f"Schema generation: `{version['schema_generation']}`", text)
+
+    def test_readme_links_versioned_docs_index(self):
+        text = (ROOT / "README.md").read_text()
+        self.assertRegex(text, r"\[Documentation index\]\(docs/INDEX\.md\)")
+
+    def test_command_reference_is_manpage_style(self):
+        text = (DOCS / "COMMAND_REFERENCE.md").read_text()
+        commands = re.findall(r"^### `([^`]+)`", text, re.M)
+        self.assertGreaterEqual(len(commands), 8)
+        for phrase in ("Global options:", "Exit code:", "Expected use:"):
+            self.assertIn(phrase, text)
+
+
+if __name__ == "__main__":
+    unittest.main()