VyOS readthedocs (mirror of https://github.com/vyos/vyos-documentation.git) https://git.amelek.net/vyos/vyos-documentation.git/atom?h=1.4 2026-05-10T14:27:05+00:00 2026-05-10T14:27:05+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-10T14:27:05+00:00 urn:sha1:e7a0bebdb5dc4b436b8b610bcb4f01afc33152e0 The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio landed. The mechanism's surface area is dead weight and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. Sibling PRs: - yuriy/remove-rst-swap-mechanism (rolling) - yuriy/remove-rst-swap-mechanism-circinus Changes: - Move 210 rst-*.rst shadow files into docs/_rst_legacy/ preserving subdirectory structure. They remain in the repo for reference; Sphinx excludes the folder via exclude_patterns. - Strip swap_sources.py invocation from docs/Makefile. - Strip rst-*.rst exclude entry and the _md_exclude.txt loader from docs/conf.py; replace with a single _rst_legacy exclude. - Delete scripts/swap_sources.py, tests/test_swap_sources.py, docs/_rst_overrides.txt. - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test. Note: .readthedocs.yml on sagitta has no jobs: block to remove (the swap was wired only at build-time via the Makefile chain on this branch). Verified: sphinx-build -b html with --keep-going produces identical warning set (409 unique — pre-existing cli.rst/aws.rst title-level warnings on this branch), identical sitemap entry count (215), identical llms.txt entry count (23), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) 2026-05-06T18:50:08+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-06T18:50:08+00:00 urn:sha1:b8b3044d3c3515d91de0f44785bfd965174867df Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/<stem>.rst to docs/**/rst-<stem>.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 2026-05-06T15:46:21+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-06T15:46:21+00:00 urn:sha1:88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 Replaces the broken #1886 with a fresh, properly-converted MyST set for the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897. This PR: - Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc fallback) on sagittas RST. Post-processed via the pipelines postprocess stage (10 ordered fixes for blanks, admonitions, label hyphens, pandoc artifacts, structural blanks, linter markers). Compared to the broken #1886 content (which was left over from an earlier stage-1-only run): zero raw `<div class=>` remnants. - For 23 stems where sagittas RST is byte-identical with currents RST (mostly stable policy/protocol pages and the 404 page), reuses currents already-validated md-*.md content rather than re-converting. - Drops cli and installation/cloud/aws from sagittas swap set: their RST has SEVERE/4 "Title level inconsistent" errors that crash rst-to-myst; they need an independent RST-source fix and are kept as RST-only for now. - Adds the per-page swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, the matching tests under tests/, _swap.txt with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile swap-wrapped targets, .readthedocs.yml swap pre/post hooks. - Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg static assets; flips html_logo to vyos-logo.webp. - Adds the MyST swap-related blocks to docs/conf.py only: myst_enable_extensions, myst_fence_as_directive, md-*.md exclude patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources setup hooks. github_version fallback set to 'sagitta' to match the branch (parallel to currents 'current' and circinuss 'circinus'). Deliberately excluded (per user direction): - llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will land separately for sagitta via #1870 plus a new sagitta-specific llms.txt template PR. The conf.py here does not pull those extensions in, so the build does not depend on the new pip packages. Verification before pushing: - 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1). - 0 files contain raw `<div class=` (the breakage that took down /en/1.5/). - conf.py copyright/version/release preserve sagittas values (2024 / 1.4 / "1.4.x (sagitta)") - not currents. - html_title from currents conf.py removed - PR #1880 is the right place for sagittas branch-localized title. Supersedes / closes on merge: - #1886 (broken converter output, would break /en/1.4/ if merged). Generated by robots https://vyos.io 2026-05-06T13:09:07+00:00 Daniil Baturin daniil@vyos.io 2026-05-06T13:09:07+00:00 urn:sha1:e066bb43eab070c58043f69efe87191b354b01e5 This reverts commit 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e. 2026-05-06T11:41:08+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-06T11:41:08+00:00 urn:sha1:22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e * feat(swap-sagitta): add incremental RST-to-MyST swap mechanism Backport of the swap mechanism from feat/incremental-myst-swap onto the sagitta release branch. Built directly on top of origin/sagitta, so the underlying RST tree is sagitta's (not current's). Mechanism: - scripts/import_myst.py — import md from myst/* with md- prefix - scripts/swap_sources.py — rename md-{name}.md → {name}.md before Sphinx builds, restore after; writes _build/_swap_state.json and _build/_swap_exclude.txt - docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build → trap restore; explicit `swap` and `restore` targets too - docs/conf.py — MyST extensions enabled; swap exclude_patterns loader; _prefer_webp builder hook so html prefers webp over png Content: - 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md alongside each {name}.rst counterpart) - 1 plain MyST-only page from myst/sagitta where no .rst exists (already at canonical name on sagitta: docs/copyright.md) - 240 .webp images from myst/sagitta (added alongside the existing PNG/JPG so RST builds keep their assets) - docs/_swap.txt populated with all 202 stems → MyST is served by default, revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback (backport from PR #1857) Fix conversion artifacts, typos, and technical inaccuracies applicable to the sagitta branch: curly quotes, typos (deamonless, cammans, amdifferent, trough), incorrect firewall command paths, missing closing brace in zone-policy, peer name inconsistencies, hardcoded passwords replaced with vault references, and md-*.md exclusion in conf.py. 🤖 Generated by [robots](https://vyos.io) * docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857 Parity backport from PR #1857 (current) — three pieces were missing on sagitta. - .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run scripts/swap_sources.py --swap before the Sphinx build and --restore after. Without this, the swap mechanism ships but never runs on RTD builds for this branch — the swap is a silent no-op. - docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse() when self.state._renderer is not present. Required for cfgcmd / opcmd / cmdincludemd directives to render correctly when included from MyST pages (the swap mechanism's whole point). Sagitta-only delta on _ext/vyos.py (the path = str(path) line on 224) is intentionally untouched. - tests/test_import_myst.py, tests/test_swap_sources.py: tests for the swap scripts. The scripts on this branch are byte-identical to current's, so the same tests apply. Travels with the branch so CI catches per-branch regressions if the scripts ever drift. 🤖 Generated by [robots](https://vyos.io) * fix(conf): skip md-*.md staging files in _copy_md_sources Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> 2023-05-11T13:27:14+00:00 rebortg github@ghlr.de 2023-05-11T13:27:14+00:00 urn:sha1:7a77ad9484679c462193395b4a0d99753c83294f 2023-02-24T12:33:42+00:00 rebortg github@ghlr.de 2023-02-24T12:33:42+00:00 urn:sha1:792938a3f94567a6617c4f9bafd002cd043acfaa 2022-12-29T20:38:58+00:00 rebortg github@ghlr.de 2022-12-29T20:38:58+00:00 urn:sha1:b15d7aa69933cad4917af81a545ab7db7f650f0f 2022-10-09T20:09:10+00:00 rebortg github@ghlr.de 2022-10-09T20:09:10+00:00 urn:sha1:8fce5147e291ebb7054f3b113da4c3da96a0a9d0 2022-07-11T20:05:48+00:00 rebortg github@ghlr.de 2022-07-11T20:05:48+00:00 urn:sha1:94b245132f4c5b5a29e41fb438c4d6a4c13bb880