diff --git a/scripts/generate_site.py b/scripts/generate_site.py index 2d5a7b57..e9269996 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -546,7 +546,7 @@ def generate_home( "", *markup.steps([ "**Pick your device.** Its page shows your BIOS folder.", - "**Run one command**, or download a ZIP file.", + "**Run one command.** Some setups have a ZIP.", "**Start a game.**", ]), "## Pick your device", @@ -719,6 +719,45 @@ def get_page_link(platform_name: str, prefix: str = "") -> str: return f"{prefix}{release_record.GET_DIR}/{platform_name}.md" +def get_page_title(platform_name: str, display: str) -> str: + """What a get/ page holds, by its name: the ZIP of a setup a release + publishes one for, the files of any other. "Download KNULLI" read as + the system's own download.""" + return f"{display} BIOS pack" if has_release_pack(platform_name) else f"{display} BIOS files" + + +def _unzip_into(platform_name: str, display: str, extract_to: str | None, parts: int) -> list[str]: + """Where the ZIP is unzipped, on the get/ page. A folder the registry + writes relative to the setup's own (`system/`, `bios/`) is named as the + setup's, with the way to find it.""" + what = "them all" if parts > 1 else "it" + if not _setup_relative(extract_to): + return [f"- Unzip {what} into {_folder_words(display, extract_to)}.", ""] + lead = GUIDES[platform_name].lead if platform_name in GUIDES else "" + return [ + f"- Unzip {what} into {_folder_words(display, extract_to)}. " + f"[Where is it?](../platforms/{platform_name}.md#where-the-files-go)", + "", + *([lead, ""] if lead else []), + ] + + +def _setup_relative(extract_to: str | None) -> bool: + """Whether the registry writes the folder relative to the setup's own + (`system/`, `Firmware/`), not as a path the device reads.""" + return bool(extract_to) and not extract_to.startswith(("/", "~", "<")) + + +def _folder_words(display: str, extract_to: str | None) -> str: + """The folder a pack or a copy goes into, in words: the device's path, + or a folder of the setup named as the setup's.""" + if not extract_to: + return "your BIOS folder" + if _setup_relative(extract_to): + return f"{display}'s `{extract_to.rstrip('/')}` folder" + return f"`{extract_to}`" + + def _pack_buttons(platform_name: str, label: str = "Pack", prefix: str = "../", display: str | None = None) -> str: """The way to the platform's ZIP from its setup page: a button to its @@ -756,7 +795,17 @@ def generate_get_page(platform_name: str) -> str: record = release_record.load_advertised() pack = release_record.pack_for(platform_name, record) released = has_release_pack(platform_name) - lines = ["---", "search: exclude", "---", "", f"# Download {display}", ""] + title = get_page_title(platform_name, display) + if released and pack and pack.get("assets"): + description = (f"The BIOS pack for {display}: {_fmt_size(pack['download_size'])} to " + "download. The address stays the same and always gives the latest ZIP.") + else: + description = f"The BIOS files for {display}: one command installs and checks them." + lines = [ + "---", "search: exclude", f"description: {json.dumps(description)}", + *_parent_front_matter((display, f"/platforms/{platform_name}/")), "---", "", + f"# {title}", "", + ] if released and pack and pack.get("assets"): parts = len(pack["assets"]) release = release_line(platform_name, record) @@ -771,9 +820,7 @@ def generate_get_page(platform_name: str) -> str: f"{_fmt_size(pack['extracted_size'])} once unzipped.", *(["- You need both parts." if parts == 2 else f"- You need all {parts} parts."] if parts > 1 else []), - f"- Unzip {'them all' if parts > 1 else 'it'} into " - + (f"`{extract_to}`." if extract_to else "your BIOS folder."), - "", + *_unzip_into(platform_name, display, extract_to, parts), *(line for text in release for line in (text, "")), version_line(platform_name, record, named=len(release) > 1), "", @@ -783,7 +830,7 @@ def generate_get_page(platform_name: str) -> str: f"No {display} ZIP yet. The next release has one. " "The command installs every file and checks it.", "", - *install_commands(f"--platform {platform_name}"), + *_setup_routes(platform_name, display), ] elif released: lines += [ @@ -796,7 +843,7 @@ def generate_get_page(platform_name: str) -> str: lines += [ no_zip_line(display), "", - *install_commands(f"--platform {platform_name}"), + *_setup_routes(platform_name, display), f"[Why no ZIP?](../{NO_ZIP_FAQ})", "", ] @@ -808,6 +855,29 @@ def generate_get_page(platform_name: str) -> str: return "\n".join(lines) +def generate_get_index() -> str: + """get/: the permanent page of every setup, grouped as the home tiles + are. A link trimmed to /get/ answered 404.""" + registry = load_platform_registry("platforms") + lines = [ + "---", "search: exclude", + 'description: "The BIOS files of every setup, one page each. Each address stays the same."', + "---", "", + "# BIOS files by setup", "", + "One page per setup. Its address stays the same, so it is the one to share.", "", + ] + for group, (label, _description) in DEVICE_GROUPS.items(): + names = [name for name, entry in registry.items() if entry.get("device_group") == group] + if not names: + continue + lines += [f"## {label}", ""] + for name in names: + display = load_platform_config(name, "platforms").get("platform", name) + lines.append(f"- [{get_page_title(name, display)}]({name}.md)") + lines.append("") + return "\n".join(lines) + + # The home tile counts the whole collection. Labelled "Files" above a table # of pack buttons, it read as what one pack contains. COLLECTION_FILES_LABEL = "Files collected" @@ -3520,6 +3590,12 @@ MISSING_IN_PLACE = "Reported missing anyway? `--check` names a wrong file." # page shows in full, so the setup page links it. SAFE_LINK = "[Is it safe?](../index.md#is-it-safe)" +# The pass line of "How to check". `--check` prints "All files up to date." +# only when no file is missing or wrong (install.py, the args.check branch +# after check_local). "0 wrong hash" alone is also what an empty folder +# prints: 0/14508 present (0 verified, 0 wrong hash). +CHECK_PASS_LINE = "All good when it says `All files up to date.`" + # Under "From your computer": a device with no network installs from the ZIP # (`--from-pack`). The id is the one wiki/installer.md gives its section. OFFLINE_LINE = ("No internet on the device? " @@ -3545,6 +3621,71 @@ def _offline_line(name: str) -> list[str]: return [OFFLINE_LINE, ""] if pack and pack.get("assets") else [] +# The route of a setup with no ZIP when the device has no network: the +# command writes to any folder named after --dest (wiki/installer.md), so a +# computer fills the device's card. The FAQ answers it with an example. +CARD_ROUTE_FAQ = "wiki/faq.md#fill-an-sd-card-from-a-computer" + + +def _card_route(name: str, display: str, guide: Guide) -> list[str]: + """The route with no network on the device, for a setup whose ZIP no + release publishes: the command run on a computer, into the card. A + setup with a ZIP has the offline line, a card setup's command already + runs on the computer. The folder named after --dest is the one the + command fills on the device (the registry's extract_to): AmberELEC's is + `/storage/roms/`, which holds `bios/` and `neogeo/`. How a computer + sees it is the reader's to name: no guide cites it.""" + if guide.on_card or _offline_line(name): + return [] + extract_to = (load_platform_registry("platforms").get(name) or {}).get("extract_to") + leaf = (extract_to or "bios").rstrip("/").rsplit("/", 1)[-1].lstrip("~") or "bios" + tabs = guide.card_run or ("windows", "macos", "linux") + args = {key: f"--platform {name} --dest " + + (f"E:\\path\\to\\{leaf}" if key == "windows" else f"/path/to/{leaf}") + for key in tabs} + if guide.run != ("device",): + lead = ("No network here? Run the command on a computer that has one, with a USB " + f"drive's folder after `--dest`. Then copy it into {_folder_words(display, extract_to)}.") + return [lead, "", *terminal_tabs(tabs, args, steps=False)] + lead = ("No network? Put the device's card in your computer. After `--dest`, " + f"name the folder the device calls `{extract_to}`.") + return [lead, "", *terminal_tabs(tabs, args, steps=False), + f"[More on SD cards](../{CARD_ROUTE_FAQ})", ""] + + +def _get_page_line(name: str, display: str) -> list[str]: + """The setup's get/ page, under the command of a setup with no ZIP: the + address a guide writer keeps. A setup with a ZIP links it by its button.""" + if has_release_pack(name): + return [] + return [f"Link to share: [{get_page_title(name, display)}](../{get_page_link(name)})", ""] + + +def _setup_routes(name: str, display: str, page_link: bool = False) -> list[str]: + """The ways to run the command for a setup no ZIP serves first, written + once for its setup page and its get/ page: the network folder from a + computer, the card from a computer when the device has no network, and + the device's own terminal. *page_link* adds the get/ page, on the setup + page only.""" + guide = GUIDES[name] + share = _network_share(name, guide) + card = _card_route(name, display, guide) + shared = _get_page_line(name, display) if page_link else [] + if share or (card and guide.run == ("device",)): + computer = ["## From your computer { #from-your-computer }", ""] + if share: + computer += [ + "Needs the device on your network. Run the command on the computer.", + "", + *terminal_tabs(("windows",), {"windows": f"--platform {name} --dest {share}"}), + SAFE_LINK, + "", + ] + return [*computer, *card, + *_guide_install(name, guide, "## On the device { #install }"), *shared] + return [*_guide_install(name, guide, "## Install"), *shared, *card] + + # Shown in the "On the device" tab of a guide that has no `terminal:` of its own. DEVICE_TERMINAL_FALLBACK = "Or fill the folder from your computer, with the ZIP." @@ -3755,7 +3896,6 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list: ]) if guide.on_card: lines += ["", ""] - share = _network_share(name, guide) if _computer_first(name, guide): lines += [ *_guide_download(name, display, guide, extract_to, @@ -3763,21 +3903,9 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list: *_offline_line(name), *_guide_install(name, guide, "## On the device { #install }"), ] - elif share: - lines += [ - "## From your computer { #from-your-computer }", - "", - "Needs the device on your network. Run the command on the computer.", - "", - *terminal_tabs(("windows",), {"windows": f"--platform {name} --dest {share}"}), - SAFE_LINK, - "", - *_guide_install(name, guide, "## On the device { #install }"), - *_guide_download(name, display, guide, extract_to, "## Download"), - ] else: lines += [ - *_guide_install(name, guide, "## Install"), + *_setup_routes(name, display, page_link=True), *_guide_download(name, display, guide, extract_to, "## Download"), *_offline_line(name), ] @@ -3788,7 +3916,7 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list: "Add `--check` to the command. It changes nothing.", "", *terminal_tabs(guide.run, check_args, steps=False), - "All good when you see `0 wrong hash`.", + CHECK_PASS_LINE, "", _check_sentence(display, cov["mode"], cov["config"], no_list), "", @@ -9573,6 +9701,9 @@ IOS_SOURCES = { "provenance": "https://wiki.provenance-emu.com/using-provenance/importing-roms", } IOS_DEVICES = ("iPhone", "iPad", "iOS", "Delta", "Provenance") +# The same names as which-pack's search terms, the section's meta field +# alone leaving "ios" unanswered. +IOS_TERMS = tuple(name.lower() for name in IOS_DEVICES) def ios_section() -> list[str]: @@ -9609,6 +9740,10 @@ def generate_which_pack() -> str: display = {key: load_platform_config(key, "platforms").get("platform", key) for key in registry} all_tabs = ("windows", "macos", "linux", "steamdeck", "android") lines = [ + "---", + f"terms: {', '.join(IOS_TERMS)}", + "---", + "", "# Get your files", "", "Pick your setup. Its page gives the folder and the command.", @@ -10294,6 +10429,7 @@ def _generate(args: argparse.Namespace) -> None: get_dir.mkdir(parents=True, exist_ok=True) for name in platform_names: write_if_changed(str(get_dir / f"{name}.md"), generate_get_page(name)) + write_if_changed(str(get_dir / "index.md"), generate_get_index()) print("Generating contributing page...") write_if_changed(str(docs / "contributing.md"), generate_contributing()) diff --git a/tests/test_release_packs.py b/tests/test_release_packs.py index 95618067..4b73d9eb 100644 --- a/tests/test_release_packs.py +++ b/tests/test_release_packs.py @@ -314,7 +314,7 @@ class EveryPlatformHasAPermanentPage(unittest.TestCase): page = generate_site.generate_get_page(name) pack = release_record.pack_for(name, record) with self.subTest(platform=name): - self.assertIn("# Download ", page) + self.assertRegex(page, r"\n# .+ BIOS (pack|files)\n") if name in RELEASED and pack: for asset in pack["assets"]: self.assertIn(