chore: merge the docs branch

This commit is contained in:
Abdessamad Derraz committed 2026-11-09 16:14:08 +01:00
commit 68e8ea449c
13 files changed
+276 -3

No files matched your search

+69
View File
@@ -636,5 +636,74 @@ class ContributorChecksFetchThePlatformsFiles(unittest.TestCase):
self.assertIn("export_native.py --all --fetch", _read("wiki/testing-guide.md"))
class ArchiveRecipesAreCountedFromTheRecipes(unittest.TestCase):
"""Every archive has a recipe in recipes/archives.json: the README and
the site's page say how many rebuild exact and canonical, counted from
that file, never typed."""
def setUp(self) -> None:
import archive_build # noqa: PLC0415
records = archive_build.load_ledger().values()
self.counts = {
"total": len(records),
"exact": sum(r["rebuild"] == "exact" for r in records),
"canonical": sum(r["rebuild"] == "canonical" for r in records),
}
self.assertEqual(archive_build.rebuild_counts(), self.counts)
self.assertEqual(self.counts["exact"] + self.counts["canonical"], self.counts["total"])
def test_the_readme_line(self) -> None:
from generate_readme import archive_line # noqa: PLC0415
line = archive_line(self.counts)
self.assertIn(line, _read("README.md").splitlines())
self.assertIn(f"**{self.counts['total']:,} archives**", line)
self.assertIn(f"{self.counts['exact']:,} byte for byte", line)
self.assertIn(f"{self.counts['canonical']:,} with the same files inside", line)
self.assertIn(f"({SITE_URL}wiki/archive-recipes/)", line)
def test_the_page_counts(self) -> None:
import generate_site # noqa: PLC0415
page = _read("wiki/archive-recipes.md")
self.assertEqual(generate_site.with_archive_counts(page, self.counts), page,
"wiki/archive-recipes.md counts are stale: run scripts/generate_site.py")
for line in generate_site.archive_recipe_lines(self.counts):
self.assertIn(line, page)
def test_the_page_command_is_the_tools(self) -> None:
command = re.search(r"python scripts/romset_recipes.py (.+)", _read("wiki/archive-recipes.md"))
source = _read("scripts/romset_recipes.py")
for flag in re.findall(r"--[a-z-]+", command.group(1)):
with self.subTest(flag=flag):
self.assertIn(f'"{flag}"', source)
class TheReadmeBadges(unittest.TestCase):
"""One row of four badges under the links, each linking its source."""
EXPECTED = (
'<p align="center">'
'<a href="https://pypi.org/project/retrobios/"><img src="https://img.shields.io/pypi/v/retrobios" alt="PyPI version"></a> '
'<a href="https://pypi.org/project/retrobios/"><img src="https://img.shields.io/pypi/pyversions/retrobios" alt="Python versions"></a> '
f'<a href="{REPO}/actions/workflows/validate.yml"><img src="{REPO}/actions/workflows/validate.yml/badge.svg?branch=main" alt="Validation"></a> '
'<a href="LICENSE"><img src="https://img.shields.io/github/license/Abdess/retrobios" alt="License"></a>'
"</p>"
)
def test_exactly_these_four(self) -> None:
readme = _read("README.md")
self.assertEqual(len(re.findall(r"<img src=\"https://(?:img\.shields\.io|github\.com)/", readme)), 4)
lines = readme.splitlines()
self.assertIn(self.EXPECTED, lines)
links = next(i for i, line in enumerate(lines) if ">Get the files</a>" in line)
self.assertEqual(lines[links + 2], self.EXPECTED)
def test_the_workflow_and_the_license_exist(self) -> None:
self.assertTrue((REPO_ROOT / ".github" / "workflows" / "validate.yml").is_file())
self.assertTrue((REPO_ROOT / "LICENSE").is_file())
if __name__ == "__main__":
unittest.main()
+49
View File
@@ -50,6 +50,55 @@ class TheGuideLeadsToTheFewestFiles(unittest.TestCase):
self.assertTrue(target.is_file() or (target / "index.html").is_file(), url)
class TheGuideDrivesTheInstaller(unittest.TestCase):
"""What an agent needs to run the installer for a user: the package
command, the plan as JSON, the exit codes, and plan, consent, act. Each
fact is held to install.py, so the guide cannot drift from it."""
def setUp(self) -> None:
import generate_installer_doc # noqa: PLC0415
self.doc = generate_installer_doc
self.text = siteagents.llms_txt([("retroarch", "RetroArch")])
self.section = self.text.split("\n## Driving the installer for a user\n", 1)[1].split("\n## ", 1)[0]
def test_the_exit_codes_are_the_installer_page_table(self) -> None:
page = (REPO_ROOT / "wiki" / "installer.md").read_text(encoding="utf-8")
table = page.split("<!-- generated: exit-codes -->", 1)[1].split("<!-- /generated: exit-codes -->")[0]
in_table = [int(code) for code in re.findall(r"^\| `(\d+)` \|", table, re.M)]
self.assertEqual(in_table, self.doc.exit_codes())
self.assertEqual([code for code, _ in siteagents.EXIT_CODES], in_table)
listed = [int(code) for code in re.findall(r"^ - `(\d+)`: ", self.section, re.M)]
self.assertEqual(listed, in_table)
def test_the_event_schema_is_the_installers(self) -> None:
import json # noqa: PLC0415
self.assertEqual(siteagents.EVENT_SCHEMA, self.doc._install.EVENT_SCHEMA)
schema = json.loads((REPO_ROOT / "schemas" / "install-events.schema.json").read_text(encoding="utf-8"))
self.assertEqual(schema["$id"], siteagents.SITE + siteagents.EVENTS_SCHEMA_PATH)
self.assertIn(f"event schema {siteagents.EVENT_SCHEMA} ", self.section)
def test_every_option_and_event_named_exists(self) -> None:
options = {flag for action in self.doc._install.build_parser()._actions
for flag in action.option_strings}
for flag in set(re.findall(r"(?<![\w-])(--[a-z][a-z-]*)", self.section)):
with self.subTest(flag=flag):
self.assertIn(flag, options)
keys = self.doc._install.EVENT_KEYS
self.assertIn("state", keys["file"])
self.assertIn("bytes_needed", keys["check"])
self.assertIn("pending", keys["summary"])
self.assertEqual(tuple(keys["end"]), ("code",))
def test_the_package_commands_and_the_pattern(self) -> None:
self.assertIn("`uvx retrobios --for-games --required-only --dry-run`", self.section)
self.assertIn("`pipx run retrobios`", self.section)
self.assertIn("`--dry-run --events`", self.section)
steps = re.findall(r"^\d\. (\w+)", self.section, re.M)
self.assertEqual(steps, ["Plan", "Consent", "Act"])
class TheSkillIsAnAgentSkill(unittest.TestCase):
"""ARD reserves text/markdown for agent skills (Lighthouse warns on a
plain Markdown entry): the setup steps are published as one."""
+1
View File
@@ -41,6 +41,7 @@ START_PAGES = {
# Reference pages written for anyone, held to the Start here budgets.
START_LEVEL_PAGES = {
"wiki/measurements.md": 300,
"wiki/archive-recipes.md": 160,
}
# Level 1: the guide part of each setup page, above its Reference heading.
SETUP_CEILING = 220
+2 -1
View File
@@ -956,7 +956,8 @@ class EventsTranscript(unittest.TestCase):
self.assertEqual(list(event), ["event", *keys[event["event"]]])
self.assertEqual(events[0]["event"], "start")
self.assertEqual(events[0]["mode"], "check")
self.assertEqual(events[-1], {"event": "end", "code": 1})
# --check that finds files missing ends on 3 (the Exit status table).
self.assertEqual(events[-1], {"event": "end", "code": 3})
class OneOptionsTable(unittest.TestCase):