From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- scripts/import_myst.py | 270 ------------------------------------------------ scripts/swap_sources.py | 201 ++++++++++++++++++----------------- 2 files changed, 109 insertions(+), 362 deletions(-) delete mode 100644 scripts/import_myst.py (limited to 'scripts') diff --git a/scripts/import_myst.py b/scripts/import_myst.py deleted file mode 100644 index b9dd7898..00000000 --- a/scripts/import_myst.py +++ /dev/null @@ -1,270 +0,0 @@ -#!/usr/bin/env python3 -"""import_myst.py — Import converted MD files from myst/* branches. - -Usage ------ - python scripts/import_myst.py --source myst/current --all - python scripts/import_myst.py --source myst/current --pages quick-start configuration/firewall/zone - python scripts/import_myst.py --source myst/current --all --force - python scripts/import_myst.py --source myst/current --all --dry-run - -Each imported file is written as md-{name}.md alongside the existing RST -file. Importing does not activate a page — use swap_sources.py for that. -""" - -import argparse -import subprocess -import sys -import warnings -from pathlib import Path -from typing import Optional - - -# --------------------------------------------------------------------------- -# Constants -# --------------------------------------------------------------------------- - -REPO_ROOT = Path(__file__).resolve().parent.parent -DOCS_DIR = REPO_ROOT / "docs" - - -# --------------------------------------------------------------------------- -# Core helpers -# --------------------------------------------------------------------------- - -def git_show(ref: str, path: str) -> Optional[bytes]: - """Run `git show {ref}:{path}` and return raw bytes, or None on error.""" - result = subprocess.run( - ["git", "show", f"{ref}:{path}"], - capture_output=True, - cwd=REPO_ROOT, - ) - if result.returncode != 0: - return None - return result.stdout - - -def list_myst_files(source: str) -> list[str]: - """Return list of MD stems from `git ls-tree -r --name-only {source} -- docs/`. - - Stems are relative to docs/ with the .md extension stripped. - Only .md files are returned. - """ - result = subprocess.run( - ["git", "ls-tree", "-r", "--name-only", source, "--", "docs/"], - capture_output=True, - text=True, - cwd=REPO_ROOT, - ) - if result.returncode != 0: - raise SystemExit( - f"import_myst: git ls-tree {source!r} failed " - f"(exit {result.returncode}): {result.stderr.strip()}" - ) - - stems = [] - for line in result.stdout.splitlines(): - line = line.strip() - if not line.endswith(".md"): - continue - # Strip leading "docs/" prefix and .md extension - rel = line[len("docs/"):] if line.startswith("docs/") else line - stem = rel[:-3] # strip ".md" - stems.append(stem) - return stems - - -def list_rst_files(docs_dir: Path) -> set[str]: - """Return set of stems (relative to docs_dir, no extension) for all *.rst files.""" - build_dir = (docs_dir / "_build").resolve() - stems = set() - for rst in docs_dir.rglob("*.rst"): - try: - rst.resolve().relative_to(build_dir) - continue # inside _build/, skip - except ValueError: - pass - rel = rst.relative_to(docs_dir) - stem = str(rel)[:-4] # strip ".rst" - stems.add(stem) - return stems - - -def import_page(stem: str, md_content: bytes, docs_dir: Path, force: bool) -> bool: - """Write md-{name}.md for the given stem. - - - Creates parent dirs as needed. - - Skips (returns False) if identical content already exists. - - Without --force: warns and skips (returns False) if different content exists. - - With --force: overwrites (returns True). - - Returns True on successful write. - - Refuses (raises ValueError) if *stem* would resolve outside *docs_dir*. - """ - p = Path(stem) - if p.is_absolute() or ".." in p.parts: - raise ValueError(f"import_myst: refusing unsafe stem {stem!r}") - name = p.name - parent = p.parent - if str(parent) == ".": - target_dir = docs_dir - else: - target_dir = docs_dir / parent - - dest = target_dir / f"md-{name}.md" - docs_root = docs_dir.resolve() - if not dest.resolve().parent.is_relative_to(docs_root): - raise ValueError(f"import_myst: refusing stem {stem!r} — escapes docs/") - - if dest.exists(): - existing = dest.read_bytes() - if existing == md_content: - return False # identical — skip silently - if not force: - warnings.warn( - f"import_myst: {dest} exists with different content; " - f"use --force to overwrite", - stacklevel=2, - ) - return False - # force=True — fall through to write - - target_dir.mkdir(parents=True, exist_ok=True) - dest.write_bytes(md_content) - return True - - -# --------------------------------------------------------------------------- -# do_import -# --------------------------------------------------------------------------- - -def do_import( - source: str, - pages: Optional[list], - all_pages: bool, - force: bool, - dry_run: bool, - docs_dir: Path, -) -> None: - """Orchestrate import from source branch. - - If --all: list MD files from source, intersect with RST stems in docs_dir, - import only those that have an RST counterpart. - If --pages: import only the listed stems. - """ - docs_dir = Path(docs_dir) - - if all_pages: - myst_stems = list_myst_files(source) - rst_stems = list_rst_files(docs_dir) - candidate_stems = [s for s in myst_stems if s in rst_stems] - else: - candidate_stems = list(pages or []) - - imported = 0 - skipped = 0 - would_import = 0 - - for stem in candidate_stems: - # Path inside the branch: docs/{stem}.md - ref_path = f"docs/{stem}.md" - content = git_show(source, ref_path) - if content is None: - print( - f"import_myst: WARNING — could not fetch {source}:{ref_path}", - file=sys.stderr, - ) - skipped += 1 - continue - - if dry_run: - print(f" (dry-run) would import {stem}") - would_import += 1 - continue - - wrote = import_page(stem, content, docs_dir, force) - if wrote: - imported += 1 - else: - skipped += 1 - - if dry_run: - print( - f"import_myst: (dry-run) would import {would_import}, " - f"skipped {skipped}.", - file=sys.stderr, - ) - else: - print( - f"import_myst: imported {imported}, skipped {skipped}.", - file=sys.stderr, - ) - - -# --------------------------------------------------------------------------- -# CLI -# --------------------------------------------------------------------------- - -def main(argv=None): - parser = argparse.ArgumentParser( - description="Import MyST MD files from a myst/* branch with md- prefix." - ) - parser.add_argument( - "--source", - required=True, - help="Git ref to import from (e.g. myst/current)", - ) - - pages_group = parser.add_mutually_exclusive_group(required=True) - pages_group.add_argument( - "--pages", - nargs="+", - metavar="STEM", - help="Specific page stems to import (e.g. quick-start configuration/firewall/zone)", - ) - pages_group.add_argument( - "--all", - action="store_true", - dest="all_pages", - help="Import all MD files that have a matching RST counterpart", - ) - - parser.add_argument( - "--force", - action="store_true", - help="Overwrite existing md- files even if content differs", - ) - parser.add_argument( - "--dry-run", - action="store_true", - help="Print what would be imported without writing files", - ) - parser.add_argument( - "--docs-dir", - type=Path, - default=None, - help="Path to docs/ directory (default: auto-detected from script location)", - ) - - args = parser.parse_args(argv) - - if args.docs_dir is None: - docs_dir = DOCS_DIR - else: - docs_dir = args.docs_dir.resolve() - - if not docs_dir.is_dir(): - parser.error(f"docs directory not found: {docs_dir}") - - do_import( - source=args.source, - pages=args.pages, - all_pages=args.all_pages, - force=args.force, - dry_run=args.dry_run, - docs_dir=docs_dir, - ) - - -if __name__ == "__main__": - main() diff --git a/scripts/swap_sources.py b/scripts/swap_sources.py index 683d5ef9..8a03085e 100644 --- a/scripts/swap_sources.py +++ b/scripts/swap_sources.py @@ -1,26 +1,36 @@ #!/usr/bin/env python3 -"""swap_sources.py — Pre-build swap/restore for incremental RST-to-MyST migration. +"""swap_sources.py — Pre-build swap/restore for the RST override mechanism. + +In this repo MD is the canonical source for migrated pages. RST kept around +under the ``rst-.rst`` prefix is a *fallback* — only consulted when a +page is explicitly listed in ``docs/_rst_overrides.txt`` to revert to the +legacy RST rendering. + +This script flips the source files in place at build time so Sphinx renders +the RST instead of the MD for the listed stems, then restores everything +after the build. Usage ----- - python scripts/swap_sources.py --swap # rename md-{name}.md → {name}.md - python scripts/swap_sources.py --restore # undo renames - python scripts/swap_sources.py --dry-run # show what would be swapped - python scripts/swap_sources.py --status # show current swap state + python scripts/swap_sources.py --swap # activate RST overrides + python scripts/swap_sources.py --restore # undo activated overrides + python scripts/swap_sources.py --dry-run # show what would be activated + python scripts/swap_sources.py --status # show current state python scripts/swap_sources.py --swap --docs-dir /path/to/docs -Swap list ---------- - docs/_swap.txt — one stem per line, relative to docs/, comments (#) skipped. - Example: - # migrated pages - configuration/firewall/zone - quick-start +The ``--swap`` flag name is kept for backward compatibility with the Makefile +and Read the Docs config; semantically it now applies RST overrides. + +Override list +------------- + docs/_rst_overrides.txt — one stem per line, relative to docs/, comments + (#) skipped. Pages listed here render from rst-.rst instead of + .md at build time. State files (in docs/_build/, gitignored) ----------------------------------------- - _swap_state.json — records completed renames - _swap_exclude.txt — RST paths to pass to Sphinx exclude_patterns + _rst_override_state.json — records completed RST activations + _md_exclude.txt — MD source paths to pass to Sphinx exclude_patterns """ import argparse @@ -34,17 +44,17 @@ from pathlib import Path # Constants # --------------------------------------------------------------------------- -STATE_FILE = "_swap_state.json" -EXCLUDE_FILE = "_swap_exclude.txt" -SWAP_LIST_FILE = "_swap.txt" -STATE_VERSION = 1 +STATE_FILE = "_rst_override_state.json" +EXCLUDE_FILE = "_md_exclude.txt" +OVERRIDE_LIST_FILE = "_rst_overrides.txt" +STATE_VERSION = 2 # bumped from 1 when the swap direction was inverted # --------------------------------------------------------------------------- # Core helpers # --------------------------------------------------------------------------- -def parse_swap_list(path: Path) -> list: +def parse_override_list(path: Path) -> list: """Read *path* and return a list of stems (comments/blanks skipped). Returns [] if the file does not exist. @@ -74,7 +84,7 @@ def _exclude_path(docs_dir: Path) -> Path: def _resolve_stem_paths(docs_dir: Path, stem: str): - """Return (md_from, md_to, rst_path) as absolute Paths for a given stem.""" + """Return (rst_from, rst_to, md_path) as absolute Paths for a given stem.""" p = Path(stem) name = p.name parent = p.parent # may be PosixPath('.') @@ -83,70 +93,71 @@ def _resolve_stem_paths(docs_dir: Path, stem: str): else: target_dir = docs_dir / parent - md_from = target_dir / f"md-{name}.md" # source: md-prefixed - md_to = target_dir / f"{name}.md" # destination: plain .md - rst_path = target_dir / f"{name}.rst" # RST that will be excluded - return md_from, md_to, rst_path + rst_from = target_dir / f"rst-{name}.rst" # source: rst-prefixed + rst_to = target_dir / f"{name}.rst" # destination: plain .rst + md_path = target_dir / f"{name}.md" # MD that will be excluded + return rst_from, rst_to, md_path # --------------------------------------------------------------------------- -# do_swap +# do_swap (apply RST overrides) # --------------------------------------------------------------------------- def do_swap(docs_dir: Path) -> None: - """Rename md-{name}.md → {name}.md for each stem in _swap.txt. + """Rename rst-{name}.rst → {name}.rst for each stem in _rst_overrides.txt. - Validates collisions, records state, writes exclude file. + The matching .md is recorded in _md_exclude.txt so Sphinx ignores it + during the build. Validates collisions, records state, writes exclude file. Rolls back all completed renames on any failure. """ docs_dir = Path(docs_dir) - swap_list = parse_swap_list(docs_dir / SWAP_LIST_FILE) - if not swap_list: - print("swap_sources: no stems in swap list, nothing to do.", file=sys.stderr) + override_list = parse_override_list(docs_dir / OVERRIDE_LIST_FILE) + if not override_list: + print("swap_sources: no stems in override list, nothing to do.", file=sys.stderr) return # Stale state: warn and auto-restore first state_path = _state_path(docs_dir) if state_path.exists(): print( - "swap_sources: WARNING — stale swap state detected. Auto-restoring before new swap.", + "swap_sources: WARNING — stale override state detected. Auto-restoring before re-applying.", file=sys.stderr, ) do_restore(docs_dir) # Validate all stems before touching the filesystem - planned = [] # list of (md_from, md_to, rst_path, stem) - for stem in swap_list: - md_from, md_to, rst_path = _resolve_stem_paths(docs_dir, stem) + planned = [] # list of (rst_from, rst_to, md_path, stem) + for stem in override_list: + rst_from, rst_to, md_path = _resolve_stem_paths(docs_dir, stem) - if not md_from.exists(): + if not rst_from.exists(): print( - f"swap_sources: skipping {stem!r} — md- source file not found: {md_from}", + f"swap_sources: skipping {stem!r} — rst- source file not found: {rst_from}", file=sys.stderr, ) continue - if not rst_path.exists(): + if not md_path.exists(): print( - f"swap_sources: skipping {stem!r} — RST file not found: {rst_path}", + f"swap_sources: skipping {stem!r} — MD file not found: {md_path}", file=sys.stderr, ) continue - if md_to.exists(): + if rst_to.exists(): raise RuntimeError( - f"collision: both RST and unprefixed .md exist for stem {stem!r}. " - f"Remove {md_to} before swapping." + f"collision: both rst- and unprefixed .rst exist for stem {stem!r}. " + f"Remove {rst_to} before applying the override." ) - planned.append((md_from, md_to, rst_path, stem)) + planned.append((rst_from, rst_to, md_path, stem)) # Execute renames with rollback on failure - completed = [] # list of (md_from, md_to) that succeeded + completed = [] # list of (rst_from, rst_to) that succeeded try: - for md_from, md_to, rst_path, stem in planned: - os.rename(md_from, md_to) - completed.append((md_from, md_to)) + for rst_from, rst_to, md_path, stem in planned: + os.rename(rst_from, rst_to) + completed.append((rst_from, rst_to)) except Exception as exc: # Rollback completed renames in reverse order for from_path, to_path in reversed(completed): @@ -164,25 +175,25 @@ def do_swap(docs_dir: Path) -> None: # Build state and exclude data using relative paths (relative to docs_dir) _build_dir(docs_dir) - swaps = [] + overrides = [] exclude_lines = [] - for md_from, md_to, rst_path, stem in planned: - rel_from = md_from.relative_to(docs_dir) - rel_to = md_to.relative_to(docs_dir) - rel_rst = rst_path.relative_to(docs_dir) - swaps.append({ + for rst_from, rst_to, md_path, stem in planned: + rel_from = rst_from.relative_to(docs_dir) + rel_to = rst_to.relative_to(docs_dir) + rel_md = md_path.relative_to(docs_dir) + overrides.append({ "stem": stem, - "md_from": str(rel_from), - "md_to": str(rel_to), - "rst_excluded": str(rel_rst), + "rst_from": str(rel_from), + "rst_to": str(rel_to), + "md_excluded": str(rel_md), }) - exclude_lines.append(str(rel_rst)) + exclude_lines.append(str(rel_md)) - state = {"version": STATE_VERSION, "swaps": swaps} + state = {"version": STATE_VERSION, "overrides": overrides} state_path.write_text(json.dumps(state, indent=2), encoding="utf-8") _exclude_path(docs_dir).write_text("\n".join(exclude_lines) + "\n", encoding="utf-8") - print(f"swap_sources: swapped {len(completed)} file(s).", file=sys.stderr) + print(f"swap_sources: applied {len(completed)} RST override(s).", file=sys.stderr) # --------------------------------------------------------------------------- @@ -190,7 +201,7 @@ def do_swap(docs_dir: Path) -> None: # --------------------------------------------------------------------------- def do_restore(docs_dir: Path) -> None: - """Undo all renames recorded in _swap_state.json (reverse order).""" + """Undo all renames recorded in _rst_override_state.json (reverse order).""" docs_dir = Path(docs_dir) state_path = _state_path(docs_dir) @@ -212,21 +223,21 @@ def do_restore(docs_dir: Path) -> None: f"expected {STATE_VERSION!r}. Inspect {state_path} manually." ) - swaps = state.get("swaps", []) + overrides = state.get("overrides", []) - for entry in reversed(swaps): - if not isinstance(entry, dict) or "md_from" not in entry or "md_to" not in entry: + for entry in reversed(overrides): + if not isinstance(entry, dict) or "rst_from" not in entry or "rst_to" not in entry: raise RuntimeError( f"swap_sources: malformed entry in {state_path}: {entry!r}. " f"Inspect manually." ) - md_from = docs_dir / entry["md_from"] # original source (md-prefixed) - md_to = docs_dir / entry["md_to"] # current location (plain .md) - if md_to.exists(): - os.rename(md_to, md_from) + rst_from = docs_dir / entry["rst_from"] # original source (rst-prefixed) + rst_to = docs_dir / entry["rst_to"] # current location (plain .rst) + if rst_to.exists(): + os.rename(rst_to, rst_from) else: print( - f"swap_sources: WARNING — expected swapped file not found: {md_to}", + f"swap_sources: WARNING — expected overridden file not found: {rst_to}", file=sys.stderr, ) @@ -235,7 +246,7 @@ def do_restore(docs_dir: Path) -> None: exclude_path = _exclude_path(docs_dir) exclude_path.unlink(missing_ok=True) - print(f"swap_sources: restored {len(swaps)} file(s).", file=sys.stderr) + print(f"swap_sources: restored {len(overrides)} RST override(s).", file=sys.stderr) # --------------------------------------------------------------------------- @@ -243,41 +254,42 @@ def do_restore(docs_dir: Path) -> None: # --------------------------------------------------------------------------- def do_dry_run(docs_dir: Path) -> None: - """Print what would be swapped without making any changes.""" + """Print what would be activated without making any changes.""" docs_dir = Path(docs_dir) - swap_list = parse_swap_list(docs_dir / SWAP_LIST_FILE) - if not swap_list: - print("(dry-run) No stems in swap list.") + override_list = parse_override_list(docs_dir / OVERRIDE_LIST_FILE) + if not override_list: + print("(dry-run) No stems in override list.") return - for stem in swap_list: - md_from, md_to, rst_path = _resolve_stem_paths(docs_dir, stem) + for stem in override_list: + rst_from, rst_to, md_path = _resolve_stem_paths(docs_dir, stem) issues = [] - if not md_from.exists(): - issues.append("md- source missing") - if not rst_path.exists(): - issues.append("RST missing") - if md_to.exists(): - issues.append("COLLISION: plain .md already exists") + if not rst_from.exists(): + issues.append("rst- source missing") + if not md_path.exists(): + issues.append("MD missing") + if rst_to.exists(): + issues.append("COLLISION: plain .rst already exists") if issues: print(f" SKIP {stem}: {', '.join(issues)}") else: - print(f" SWAP {md_from.name} → {md_to.name} (in {md_from.parent.relative_to(docs_dir) if md_from.parent != docs_dir else '.'})") + rel_dir = rst_from.parent.relative_to(docs_dir) if rst_from.parent != docs_dir else "." + print(f" APPLY {rst_from.name} → {rst_to.name} (in {rel_dir})") def do_status(docs_dir: Path) -> None: - """Show current swap state.""" + """Show current override state.""" docs_dir = Path(docs_dir) state_path = _state_path(docs_dir) if not state_path.exists(): - print("swap_sources: no active swap state.") + print("swap_sources: no active RST overrides.") return state = json.loads(state_path.read_text(encoding="utf-8")) - swaps = state.get("swaps", []) - print(f"swap_sources: {len(swaps)} file(s) currently swapped:") - for entry in swaps: - print(f" {entry['md_from']} → {entry['md_to']} (excludes {entry['rst_excluded']})") + overrides = state.get("overrides", []) + print(f"swap_sources: {len(overrides)} RST override(s) currently active:") + for entry in overrides: + print(f" {entry['rst_from']} → {entry['rst_to']} (excludes {entry['md_excluded']})") # --------------------------------------------------------------------------- @@ -286,13 +298,18 @@ def do_status(docs_dir: Path) -> None: def main(argv=None): parser = argparse.ArgumentParser( - description="Swap md-prefixed MyST files in place of RST files before Sphinx builds." + description="Activate rst-prefixed RST files as the build source for stems " + "listed in docs/_rst_overrides.txt." ) group = parser.add_mutually_exclusive_group(required=True) - group.add_argument("--swap", action="store_true", help="Perform swap") - group.add_argument("--restore", action="store_true", help="Restore original files") - group.add_argument("--dry-run", action="store_true", help="Show what would be swapped") - group.add_argument("--status", action="store_true", help="Show current swap state") + group.add_argument("--swap", action="store_true", + help="Apply RST overrides (rename rst-.rst → .rst)") + group.add_argument("--restore", action="store_true", + help="Restore original files after a previous --swap") + group.add_argument("--dry-run", action="store_true", + help="Show what would be applied") + group.add_argument("--status", action="store_true", + help="Show current override state") parser.add_argument( "--docs-dir", -- cgit v1.2.3