docs: turn the readme into a front page

The README ran 211 lines and 2,000 words: five commands with options,
an 18-row download table, coverage figures and the build commands, all
before the help. It now says what the project does, gives the line that
installs for Windows and for the rest, shows it, lists the six ZIPs and
the setups that install by command, and leads to the site, where the
figures and every option live. The build commands sit in a closed block.
No personal pronoun is left in its text.

tests/test_audit_regressions.py

@@ -56,8 +56,8 @@ class ReadmeRegressions(unittest.TestCase):
 
     def _quick_install(self) -> str:
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
-        return readme.split("## Quick install", 1)[1].split(
-            "## Download BIOS packs", 1
+        return readme.split("## Install in one line", 1)[1].split(
+            "## Or download a ZIP", 1
         )[0]
 
     def test_advertised_bootstrap_urls_are_the_shipped_ones(self):
@@ -1121,7 +1121,10 @@ class CatalogRatioRegressions(unittest.TestCase):
         match = re.search(
             r"\*\*([\d,]+) of ([\d,]+) system files\*\* matched to", readme
         )
-        self.assertIsNotNone(match, "README no longer states the catalog ratio")
+        if match is None:
+            # The README states no ratio since it leads to the site: a ratio
+            # it states must still be the database's.
+            return
         matched, total = (int(g.replace(",", "")) for g in match.groups())
         self.assertEqual(matched, count_catalog_matched(db))
         self.assertEqual(total, compute_composition(db)["systems"]["files"])

tests/test_doc_pages.py

@@ -340,7 +340,7 @@ class FilesColumnParagraph(unittest.TestCase):
         paragraph = next(p for p in readme.split("\n\n") if "The Files column" in p)
         self.assertNotIn("\n", paragraph.strip())
         after = readme.split(paragraph, 1)[1].lstrip("\n")
-        self.assertTrue(after.startswith("| Platform | Files |"))
+        self.assertTrue(after.startswith("| Setup | Files |"))
 
 
 class PageOpenings(unittest.TestCase):
@@ -769,14 +769,12 @@ class ReadmeInstallerOptions(unittest.TestCase):
         import generate_readme
 
         source = inspect.getsource(generate_readme.generate_readme)
-        self.assertIn('install_command("powershell", "--check")', source)
         self.assertIn("wiki/installer/#passing-options", source)
         self.assertIn("## Passing options", _page("installer.md"))
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
-        quick = _section(readme, "Quick install")
-        from siteguides import INSTALL_PS1
-
-        self.assertIn(f"&([scriptblock]::Create((irm {INSTALL_PS1}))) --check", quick)
+        quick = _section(readme, "Install in one line")
+        # The README gives the bare line and sends options to the page that
+        # writes their PowerShell form: an option after `| iex` reaches iex.
         self.assertIn("wiki/installer/#passing-options", quick)
         self.assertNotRegex(readme, r"(?m)^irm \S+ \| iex \S")
 
@@ -791,7 +789,7 @@ class PublishedNumbersShareOneFormat(unittest.TestCase):
 
         readme_source = inspect.getsource(generate_readme.generate_readme)
         self.assertNotIn("size_mb", readme_source)
-        self.assertIn("format_size(total_size)", readme_source)
+        self.assertIn("format_size(size)", readme_source)
         self.assertIn("{total_files:,}", inspect.getsource(generate_site))
         self.assertEqual(generate_readme.format_size(16011 * 1024 * 1024), "15.6 GB")
 
@@ -1713,9 +1711,7 @@ class ReadmeKeepsItsPointers(unittest.TestCase):
         """The README sent a reader to 'build your own pack below' for a bare
         minimum, and the block below never named --required-only."""
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
-        self.assertIn("For a bare minimum, build your own pack below.", readme)
-        block = readme[readme.index("## Build your own pack"):]
-        block = block[:block.index("\n## ", 1)]
+        block = readme[readme.index("<summary><strong>For developers"):readme.index("</details>")]
         self.assertIn("--required-only", block)
 
     def test_unsourceable_files_are_not_said_to_exist_nowhere(self):
@@ -1725,7 +1721,8 @@ class ReadmeKeepsItsPointers(unittest.TestCase):
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
         self.assertNotIn("sourced at all", readme)
         self.assertNotIn("nobody has made", readme)
-        self.assertRegex(readme, r"more the collection does not hold and does not serve by name")
+        # The README names no count: the gap analysis it links does, by reason.
+        self.assertIn("gaps/", readme)
 
 
 class ArchitectureStatesTheArbitration(unittest.TestCase):
@@ -2041,8 +2038,8 @@ class BuildYourOwnPackSaysWhatTheCloneCosts(unittest.TestCase):
         line = generate_readme.clone_line(db)
         self.assertIn("git clone --depth 1", line)
         self.assertRegex(line, r"over \d+(\.\d)? GB")
-        section = _section((ROOT / "README.md").read_text(encoding="utf-8"),
-                           "Build your own pack")
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+        section = readme[readme.index("<summary><strong>For developers"):readme.index("</details>")]
         self.assertIn("git clone --depth 1", section)
 
     def test_advanced_usage_names_the_shallow_clone(self):

tests/test_doc_surfaces.py

@@ -191,16 +191,17 @@ class DownloadLinksKeepTheirAddress(unittest.TestCase):
         from common import list_registered_platforms, list_release_pack_platforms
 
         readme = _read("README.md")
-        table = _section(readme, "## Download BIOS packs")
+        table = _section(readme, "## Or download a ZIP")
         self.assertNotIn("/releases/download/", table)
         released = set(list_release_pack_platforms("platforms"))
+        rows = [line for line in table.splitlines() if line.startswith("| ")]
         for key in list_registered_platforms("platforms"):
             with self.subTest(platform=key):
+                # Every setup's lasting page is linked: a ZIP's from its row,
+                # the others from the line that says they install by command.
                 self.assertIn(f"]({SITE_URL}get/{key}/)", table)
-                row = next(line for line in table.splitlines()
-                           if f"get/{key}/)" in line)
-                if key not in released:
-                    self.assertIn("[Use the command]", row)
+                in_rows = any(f"get/{key}/)" in row for row in rows)
+                self.assertEqual(in_rows, key in released)
 
     def test_the_download_page_rows_link_get_pages(self):
         page = _which_pack()
@@ -258,7 +259,7 @@ class TheReadmeLeadsBeginnersToTheirPages(unittest.TestCase):
     def test_quick_install_links_the_start_pages(self):
         # The code block holds `#` comment lines, so the section runs to
         # the next level-two heading.
-        section = _read("README.md").split("## Quick install", 1)[1].split("\n## ", 1)[0]
+        section = _read("README.md").split("## Install in one line", 1)[1].split("\n## ", 1)[0]
         for page in ("first-install", "troubleshooting", "faq"):
             with self.subTest(page=page):
                 self.assertIn(f"wiki/{page}/)", section)

tests/test_release_packs.py

@@ -284,9 +284,9 @@ class EverySurfaceSaysWhy(unittest.TestCase):
 
     def test_the_readme_rows_read_use_the_command(self):
         readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
-        row = next(line for line in readme.splitlines() if line.startswith("| KNULLI |"))
-        self.assertIn(f"[Use the command]({SITE}get/knulli/)", row)
-        self.assertIn("ZIPs are made for the setups most people download.", readme)
+        line = next(text for text in readme.split("\n\n") if "ZIPs are made for the setups most people download." in text)
+        self.assertIn(f"[KNULLI]({SITE}get/knulli/)", line)
+        self.assertIn("install with the line above", line)
 
     def test_the_faq_answers_why(self):
         faq = (REPO_ROOT / "wiki" / "faq.md").read_text(encoding="utf-8")

tests/test_site_bootstrap.py

@@ -271,7 +271,7 @@ class GeneratedSurfaces(unittest.TestCase):
 
     def test_the_readme_shows_the_short_form(self):
         readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
-        quick = readme.split("## Quick install", 1)[1].split("\n## ", 1)[0]
+        quick = readme.split("## Install in one line", 1)[1].split("\n## ", 1)[0]
         self.assertIn(f"\n{install_command('sh')}\n", quick)
         self.assertIn(f"\n{install_command('powershell')}\n", quick)
         self.assertNotIn("raw.githubusercontent.com", quick)

tests/test_site_demo.py

@@ -84,8 +84,8 @@ class TheReadmeShowsTheGif(unittest.TestCase):
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
         line = f"![{generate_readme.demo_description()}]({generate_readme.DEMO_GIF})"
         self.assertIn(line, readme)
-        self.assertLess(readme.index("## Quick install"), readme.index(line))
-        self.assertLess(readme.index(line), readme.index("## Download BIOS packs"))
+        self.assertLess(readme.index("## Install in one line"), readme.index(line))
+        self.assertLess(readme.index(line), readme.index("## Or download a ZIP"))
 
     def test_the_description_names_what_the_recording_measured(self):
         facts = _facts()

tests/test_site_integration.py

@@ -237,7 +237,7 @@ class FaqInstallsFromWhatYouHold(unittest.TestCase):
             word = rule.name.split()[0]
             with self.subTest(share=rule.name):
                 self.assertIn(word, section)
-                self.assertRegex(readme, rf"# SD card mounted on a PC: .*\b{word}\b")
+                self.assertRegex(readme, rf"\b{word}\b[^.]*SD card plugged into the computer is found by itself")
         # The label the first screen gives a card found: "Onion SD card".
         self.assertEqual(install._card_word(("retroarch", Path("/x/BIOS"), "Onion")), "SD card")
         self.assertEqual(install._card_word(("batocera", Path("/x/bios"), "Batocera")),