From 6ae9e461bd81780cad7f972b9f5465019eee159b Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:16:32 +0100 Subject: [PATCH] docs: name the steps the pipeline skip flags skip --skip-packs said --skip-docs would stop after verify while 4d and 4e still run, and the tools.md flag table left 8b out of --skip-docs. The help, the usage and the flag table now name the steps the step table marks. --- scripts/pipeline.py | 14 +++++++------- tests/test_doc_pages.py | 31 +++++++++++++++++++++++++++++++ wiki/tools.md | 6 +++--- 3 files changed, 41 insertions(+), 10 deletions(-) diff --git a/scripts/pipeline.py b/scripts/pipeline.py index 11d8c3f24..244eeb307 100644 --- a/scripts/pipeline.py +++ b/scripts/pipeline.py @@ -35,8 +35,8 @@ come from .cache/large/ only. Usage: python scripts/pipeline.py # active platforms python scripts/pipeline.py --include-archived # all platforms - python scripts/pipeline.py --skip-packs # steps 0 to 3b, 4d, 7 and 8 - python scripts/pipeline.py --skip-docs # skip steps 7 and 8 + python scripts/pipeline.py --skip-packs # skip steps 4, 4b, 4c, 5 and 6 + python scripts/pipeline.py --skip-docs # skip steps 7, 8 and 8b python scripts/pipeline.py --offline # no network, see above """ @@ -698,13 +698,13 @@ def main() -> None: parser.add_argument( "--skip-packs", action="store_true", - help="Skip steps 4 to 6 except 4d: packs, manifests and their checks. " - "Steps 7 and 8 still rewrite README.md and the site pages in website/, " - "add --skip-docs to " - "stop after verify", + help="Skip steps 4, 4b, 4c, 5 and 6: packs, manifests and their checks. " + "Step 4d still gates the run, step 4e still rewrites install/games/, and " + "steps 7 to 8b rewrite README.md and the site unless --skip-docs is given", ) parser.add_argument( - "--skip-docs", action="store_true", help="Skip README and site generation" + "--skip-docs", action="store_true", + help="Skip steps 7, 8 and 8b: README, installer page and site" ) parser.add_argument( "--offline", action="store_true", diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py index 409e80248..4a3ef5d69 100644 --- a/tests/test_doc_pages.py +++ b/tests/test_doc_pages.py @@ -1794,5 +1794,36 @@ class ReportExcerptIsTheRun(unittest.TestCase): self.assertIn(line, printed) +class SkipFlagsNameTheSteps(unittest.TestCase): + """--skip-packs said "add --skip-docs to stop after verify" while 4d and + 4e still ran, and the flag table left 8b out of --skip-docs.""" + + STEP = r"\b\d[a-z]?\d?\b" + + def test_the_flag_row_the_help_and_the_usage_agree_with_the_step_table(self): + page = (ROOT / "wiki" / "tools.md").read_text(encoding="utf-8") + table = page.split("Pipeline steps:", 1)[1].split("Pipeline flags:", 1)[0] + source = (ROOT / "scripts" / "pipeline.py").read_text(encoding="utf-8") + helps = {} + for node in ast.walk(ast.parse(source)): + if (isinstance(node, ast.Call) and getattr(node.func, "attr", "") == "add_argument" + and node.args and isinstance(node.args[0], ast.Constant)): + helps.update({node.args[0].value: ast.literal_eval(kw.value) + for kw in node.keywords if kw.arg == "help"}) + for flag in ("--skip-packs", "--skip-docs"): + steps = set() + for row in table.splitlines(): + cells = [c.strip() for c in row.split("|")] + if len(cells) > 3 and cells[3].startswith(f"`{flag}`"): + steps.add(cells[1]) + self.assertTrue(steps) + row = re.search(rf"^\| `{flag}` \| skip steps ([^.|]*)", page, re.M).group(1) + usage = re.search(rf"pipeline\.py {flag} +# skip steps (.*)$", source, re.M).group(1) + said = helps[flag].split(":", 1)[0] + for text in (row, usage, said): + with self.subTest(flag=flag, text=text): + self.assertEqual(set(re.findall(self.STEP, text)), steps) + + if __name__ == "__main__": unittest.main() diff --git a/wiki/tools.md b/wiki/tools.md index 6cce3c211..d691b8917 100644 --- a/wiki/tools.md +++ b/wiki/tools.md @@ -15,7 +15,7 @@ Run everything in sequence: ```bash python scripts/pipeline.py --offline # DB + verify + packs + manifests + integrity + readme + site -python scripts/pipeline.py --offline --skip-packs # DB + verify + readme + site +python scripts/pipeline.py --offline --skip-packs # no packs or manifests python scripts/pipeline.py --offline --skip-docs # skip readme + site generation python scripts/pipeline.py --offline --target switch # filter by hardware target python scripts/pipeline.py --offline --with-truth # include truth generation + diff @@ -63,8 +63,8 @@ Pipeline flags: | Flag | Effect | |------|--------| | `--offline` | skip every step that needs the network (2, 2a, 2a2, 2b, 2b2), and pack only the release assets already in `.cache/large/` | -| `--skip-packs` | skip steps 4, 4b, 4c, 6 and the consistency check. README and site are still rewritten unless `--skip-docs` is given too | -| `--skip-docs` | skip steps 7 and 8 | +| `--skip-packs` | skip steps 4, 4b, 4c, 5 and 6. Steps 4d and 4e still run, and README and site are still rewritten unless `--skip-docs` is given too | +| `--skip-docs` | skip steps 7, 8 and 8b | | `--include-archived` | include archived platforms in verify, packs, truth and export | | `--target TARGET` | filter verify, packs and truth by hardware target | | `--source {platform,truth,full}` | pack file source, passed through to `generate_pack.py`. Refused with `--skip-packs` |