From b402a8b917d30ed009f0a500c8c6c731d7422c06 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 20 Oct 2026 02:24:36 +0200
Subject: [PATCH] docs: install markdown with the test dependencies

CONTRIBUTING and the testing guide installed pyyaml and jsonschema only, while the CI test job also installs markdown. On a contributor's machine the wiki heading test skipped and the run read OK. Both name it now, and a test compares them to the packages the tests import.
---
 CONTRIBUTING.md               |  2 +-
 scripts/generate_readme.py    |  2 +-
 tests/test_site_validation.py | 16 ++++++++++++++++
 wiki/testing-guide.md         | 10 +++++-----
 4 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4ed74f74..a066f461 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,7 +44,7 @@ Full walkthrough: [profiling guide](https://abdess.github.io/retrobios/wiki/prof
 The checks CI runs on a pull request (Python 3.12 or newer):
 
 ```bash
-pip install pyyaml "jsonschema[format-nongpl]"
+pip install pyyaml "jsonschema[format-nongpl]" markdown
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --emulator NAME --strict  # each profile the branch adds
diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py
index 574ed11a..b090d9f5 100644
--- a/scripts/generate_readme.py
+++ b/scripts/generate_readme.py
@@ -729,7 +729,7 @@ Full walkthrough: [profiling guide]({link("wiki/profiling")}).
 The checks CI runs on a pull request (Python 3.12 or newer):
 
 ```bash
-pip install pyyaml "jsonschema[format-nongpl]"
+pip install pyyaml "jsonschema[format-nongpl]" markdown
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --emulator NAME --strict  # each profile the branch adds
diff --git a/tests/test_site_validation.py b/tests/test_site_validation.py
index aab67b3c..9f75980b 100644
--- a/tests/test_site_validation.py
+++ b/tests/test_site_validation.py
@@ -202,6 +202,22 @@ class EveryTestDependencyIsInstalledInCi(unittest.TestCase):
         )
         self.assertEqual(missing, [])
 
+    def test_a_contributor_installs_what_ci_installs(self):
+        # The contributing page installed pyyaml and jsonschema only, so the
+        # markdown test skipped on a contributor's machine and ran in CI.
+        from generate_readme import generate_contributing
+
+        command = next(
+            line for line in generate_contributing().splitlines() if "pip install" in line
+        )
+        guide = (Path(__file__).resolve().parents[1] / "wiki" / "testing-guide.md").read_text(
+            encoding="utf-8"
+        )
+        for package in self.PACKAGES.values():
+            with self.subTest(package=package):
+                self.assertIn(package, command)
+                self.assertIn(package, guide)
+
 
 
 class TheTestingGuideNamesEveryModule(unittest.TestCase):
diff --git a/wiki/testing-guide.md b/wiki/testing-guide.md
index c860325b..388b432f 100644
--- a/wiki/testing-guide.md
+++ b/wiki/testing-guide.md
@@ -25,11 +25,11 @@ python -m unittest tests.test_install tests.test_install_cores -v
 The table below says which module covers what.
 
 Running the build needs Python 3.12 and `pyyaml` alone, and so does most of the suite. The
-schema contract tests also need `jsonschema[format-nongpl]`, which the CI
-installs: without it they are reported as skipped, so install it before a pull
-request that touches a profile, a platform file or a schema
-(`pip install "jsonschema[format-nongpl]"`). No test framework beyond the
-standard library `unittest` module.
+schema contract tests also need `jsonschema[format-nongpl]`, and one site test
+renders a wiki line with `markdown`. The CI installs both: without them those
+tests are reported as skipped, so install them before a pull request
+(`pip install "jsonschema[format-nongpl]" markdown`). No test framework beyond
+the standard library `unittest` module.
 
 ## Modules at a glance