From 548a1bc6365085632bb85f1f3f9323a959faaf0e Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Fri, 6 Nov 2026 04:06:45 +0100
Subject: [PATCH] docs: regenerate installer samples with manifests

testing-guide listed the generated artifacts without derivable.json and
the run samples of wiki/installer.md, and tools.md gave the manifest
command alone. The nightly's commit rules also had no place for the two
files its offline pipeline rewrites, so autorun stopped on them.
---
 automation/jobs.yml     |  5 +++--
 tests/test_doc_pages.py | 22 ++++++++++++++++++++++
 wiki/testing-guide.md   |  7 +++++--
 wiki/tools.md           |  1 +
 4 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/automation/jobs.yml b/automation/jobs.yml
index 7d544f6f7..7bcd56551 100644
--- a/automation/jobs.yml
+++ b/automation/jobs.yml
@@ -87,8 +87,9 @@ jobs:
         body: >-
           Regenerated by the offline pipeline, database.json and the
           manifests computed twice with the same result.
-        paths: [database.json, install/*.json, install/targets/*.json, install/games/*.json,
-                install/games/*/*.json, README.md, CONTRIBUTING.md, website/src/data/*.json]
+        paths: [database.json, derivable.json, install/*.json, install/targets/*.json,
+                install/games/*.json, install/games/*/*.json, README.md, CONTRIBUTING.md,
+                wiki/installer.md, website/src/data/*.json]
     scratch: [dist, tmp/autorun]
 
   bios-integrity:
diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index fcf42b311..0a3939f78 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -1900,6 +1900,28 @@ class SkipFlagsNameTheSteps(unittest.TestCase):
                     self.assertEqual(set(re.findall(self.STEP, text)), steps)
 
 
+class TheInstallerSamplesTravelWithTheManifests(unittest.TestCase):
+    """A manifest refresh (c624a820f) went out without the run samples of
+    wiki/installer.md, which count what the manifests hold, and CI turned
+    red. The rule lived in no page, and the nightly's commit rules had no
+    place for the samples the gate's pipeline rewrites."""
+
+    def test_the_pages_and_the_nightly_carry_them(self):
+        import autorun  # noqa: PLC0415
+
+        guide = (WIKI / "testing-guide.md").read_text(encoding="utf-8")
+        for name in ("wiki/installer.md", "derivable.json", "generate_installer_doc.py"):
+            self.assertIn(name, guide)
+        tools = (WIKI / "tools.md").read_text(encoding="utf-8")
+        manifests = tools.index("--all --manifest --output-dir install/")
+        self.assertIn("generate_installer_doc.py", tools[manifests:manifests + 300])
+        nightly = autorun.load_jobs()["nightly"]
+        patterns = [p for rule in nightly.commits for p in rule.paths]
+        for path in ("wiki/installer.md", "derivable.json", "install/retroarch.json"):
+            with self.subTest(path=path):
+                self.assertTrue(any(autorun.path_matches(p, path) for p in patterns))
+
+
 class APlatformListIsDescribedNotJudged(unittest.TestCase):
     """adding-a-platform opened on files a platform's own list "leaves out",
     read first by the maintainer of that platform: "does not name" says the
diff --git a/wiki/testing-guide.md b/wiki/testing-guide.md
index a8cc0e711..69a865780 100644
--- a/wiki/testing-guide.md
+++ b/wiki/testing-guide.md
@@ -463,9 +463,12 @@ refactor: extract shared utils to common.py
 
 Files are staged by name, never with `git add -A` or `git add .`, which sweep in
 deletions and work that is not yours. Generated artifacts (`database.json`,
-`install/*.json`, `README.md`, `CONTRIBUTING.md`, `exports/`) are committed
+`derivable.json`, `install/*.json`, `README.md`, `CONTRIBUTING.md`, `exports/`,
+the generated tables and run samples of `wiki/installer.md`) are committed
 with the data they derive from, never alone: a manifest committed before the
-files it points at gives the installer a 404.
+files it points at gives the installer a 404. The run samples count what the
+manifests hold, so `generate_installer_doc.py` runs after every manifest
+regeneration and its output goes in the same commit.
 
 ## CI integration
 
diff --git a/wiki/tools.md b/wiki/tools.md
index 5992abbcd..c74739572 100644
--- a/wiki/tools.md
+++ b/wiki/tools.md
@@ -238,6 +238,7 @@ python scripts/generate_pack.py --all --offline       # cache-only, never open t
 # Install manifests (consumed by install.py)
 python scripts/generate_pack.py --all --manifest --output-dir install/
 python scripts/generate_pack.py --manifest-targets --output-dir install/targets/
+python scripts/generate_installer_doc.py  # run samples of wiki/installer.md, from the manifests
 ```
 
 Packs include platform baseline files plus files required by the platform's cores.