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-12T06:05:31+00:00 2026-05-12T06:05:31+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-12T06:05:31+00:00 urn:sha1:139952dc4d1e1d1b5496bd564b7e047917e6587c The auto-backport PR #1998 committed literal git conflict markers into docs/conf.py because _copy_md_sources sits before _write_llms_txt on sagitta but after it on rolling — cherry-pick failed to locate the patch context and dropped the entire new function as a duplicate with markers. Removes the conflict-marker block and applies the actual 3-line guard to the existing _copy_md_sources function. Build was failing with "SyntaxError: invalid syntax (conf.py)". 🤖 Generated by [robots](https://vyos.io) 2026-05-12T06:00:17+00:00 Quill Cronwall quilljazz@gmail.com 2026-05-11T11:12:50+00:00 urn:sha1:79906ff29adfe59e61802dadfe846aa2e52e4289 (cherry picked from commit ec6f33f3c256e839b443bb2baac14bff32132811) # Conflicts: # docs/conf.py 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-07T15:02:34+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T14:53:41+00:00 urn:sha1:c3a0426c7b4f2e874ce4d568c908e1f619dfaa4e Read COOKIEBOT_ID from the environment via conf.py html_context, replacing the hardcoded data-cbid value in layout.html. Guards tightened to {% if gtm_id and cookiebot_id %} so neither GTM nor Cookiebot loads unless both IDs are present. 🤖 Generated by [robots](https://vyos.io) 2026-05-07T15:02:34+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T14:19:45+00:00 urn:sha1:f3f8b5c0744fad94808306a019739cad3113e6e2 Move the Google Tag Manager container ID out of the template and into conf.py via os.environ.get('GTM_ID', ''), exposed to Jinja via html_context. Set GTM_ID in the RTD project environment variables. 🤖 Generated by [robots](https://vyos.io) 2026-05-07T07:10:21+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T07:10:21+00:00 urn:sha1:672b331fdaaa91e5a0c23c4abb9609c6f4c6a359 # Conflicts: # docs/conf.py 2026-05-07T06:48:08+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:48:08+00:00 urn:sha1:e42de316317d100d87c720e5f7c6df3373ee46dc Last residual `.html` reference in the `_write_llms_txt` hook comments — the html_baseurl-empty failure-path comment said "rendering /quick-start.html etc." but the template now emits `.md` URLs. Update the example to `/quick-start.md` to match the actual output. Comment-only change. Same fix applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874), [#1876](https://github.com/vyos/vyos-documentation/pull/1876), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903). Addresses Copilot review feedback on PR #1903. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) 2026-05-07T06:40:49+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:40:49+00:00 urn:sha1:d0d7980ad2301ad98ed05bd3cbbc13109a989f83 The previous comment on `_write_llms_txt` (and on the LLM-Facing Files section in CLAUDE.md) justified the `dirhtml` skip by claiming the template's `.html` URLs wouldn't resolve under `dirhtml` output. That became stale after [#1874@5fe7f9ad](https://github.com/vyos/vyos-documentation/pull/1874/commits/5fe7f9ad) (and parity commits on [#1876](https://github.com/vyos/vyos-documentation/pull/1876)/[#1903](https://github.com/vyos/vyos-documentation/pull/1903)) pivoted the curated template to `.md` URLs — `_copy_md_sources` puts `.md` files at their source-relative paths regardless of builder, so the rendered llms.txt would actually resolve fine under `dirhtml` now. The real reason we skip `dirhtml` is simpler: production publishes only via the `html`/`readthedocs` builders, and we don't render llms.txt for builds we don't ship. Local `make dirhtml` is a developer convenience, not a publish target. Reword the conf.py comment and the CLAUDE.md section to say that plainly. No code-behavior change. Addresses Copilot review feedback on PR #1874 (3 threads on docs/conf.py, docs/_templates/llms.txt.j2, and CLAUDE.md flagging the inconsistency). \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) 2026-05-07T06:25:56+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:25:56+00:00 urn:sha1:ec20a9585043c11cf16be5cb9543f44a3763ee03 The llms.txt template renders plain text (markdown), not HTML, so the HTML autoescape rules that bandit/ruff S701 flags don't apply. Explicit `autoescape=False` silences the lint while documenting the intent — there's no HTML context to escape into here. Behavior unchanged (Jinja's default `autoescape=False` was already in effect); this just makes it visible. Same change applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current), [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903) (circinus). Addresses CodeRabbit review feedback (S701) on PR #1876. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) 2026-05-07T06:16:25+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:16:25+00:00 urn:sha1:1b3277b4579a7b0a7231e3cfd5b98ac405ba45c0 Switch from `Environment.from_string(tpl_path.read_text(...))` to `Environment(loader=FileSystemLoader(...)).get_template('llms.txt.j2')`. When `StrictUndefined` raises on a typo in `llms.txt.j2` (e.g. `{{ relase }}`), the traceback now references the real template filename and line number instead of an anonymous in-memory template. That makes debugging template typos materially easier without changing any other behavior — same fail-fast guard, same trailing-newline handling, same rendered output. Same change applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current), [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903) (circinus) so the hook stays identical across branches. Addresses CodeRabbit/Copilot review feedback on PR #1903. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io)