vyos-documentation.git/docs/_ext, branch mergify/bp/circinus/pr-2117

fix(ext): parse cmdincludemd content as RST so legacy `_include/*.txt` directives render

2026-05-12T13:40:46+00:00

The `_include/*.txt` library is written in reStructuredText (`.. cfgcmd::`, `.. code-block::`, `.. note::`, `.. cmdinclude::`). After the RST→MyST migration, the `{cmdincludemd}` fence on .md pages routed include content through `MockState.nested_parse`, which in MyST 2.0 simply replays the content through the MyST renderer (see myst_parser/mocking.py:153). RST directives in the .txt file then rendered as literal paragraph text:

.. cmdinclude:: /_include/interface-description.txt

.. cfgcmd:: set interfaces ethernet ...

.. code-block:: none

User-visible symptom (reported on rolling docs): the Ethernet, dummy, tunnel, bonding, bridge, macsec, vxlan, l2tpv3, pseudo-ethernet, virtual-ethernet, and wireless pages all showed unprocessed `.. cfgcmd::` and `.. cmdinclude::` directives instead of styled command boxes. Fix: mirror MyST's own `{eval-rst}` plumbing (`MockRSTParser().parse(text, doc)` per `mdit_to_docutils/base.py:1655`). Build a fresh document that inherits the outer document's settings + reporter, run `MockRSTParser` over the substituted include content, and graft the resulting children back into the calling document with explicit-target registration. Keeps the Sphinx env available to `cfgcmd`/`opcmd`/`cmdinclude` directives. Verified locally on rolling (Sphinx 7.x, myst-parser 2.0): zero literal `cfgcmd::` / `cmdinclude::` / `code-block::` / `opcmd::` / `note::` / `include::` strings remain in any built HTML page under `configuration/`, `automation/`, `installation/`, `operation/`, `vpp/`; all 11 affected interface pages now render proper `cfgcmd-heading` / `cfgcmd-body` blocks (e.g. ethernet.html: 160, wireless.html: 172, dummy.html: 4). 🤖 Generated by [robots](https://vyos.io) (cherry picked from commit 9c815d689a2a4a5d433ba15154cb606bd986fc8d)

feat: import MyST swap mechanism, llms.txt feature, and content from current

2026-05-06T14:47:58+00:00

Replaces the broken #1885/#1869/#1875 trio with a single PR for circinus. This PR: - Imports 254 md-*.md files from currents working MyST conversion (the broken converter that produced #1885s md-*.md files is not used here; currents files are correct as verified on /en/rolling/). - Adds the per-page RST-to-MyST swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, tests, _swap.txt, _ext/vyos.py and Makefile swap-wrapped targets, .readthedocs.yml pre/post hooks. - Replaces 175 .jpg/.png with 187 .webp images for swapped pages. - Adds the llms.txt + sitemap feature (sphinx_llms_txt, sphinx_sitemap) with circinus-tailored html_baseurl https://docs.vyos.io/en/1.5/ and curated docs/_html_extra/llms.txt for 1.5.x. - Updates docs/_html_extra/robots.txt with AI crawler Allow rules and the /en/1.5/sitemap.xml reference. - Drops configuration/service/suricata from the swap set (no matching RST sibling on circinus; suricata is a current-only feature). Supersedes: - #1885 (broken md-*.md converter output) - #1869 (LLM doc adaptation backport, bundled here) - #1875 (llms.txt circinus, bundled here) Generated by robots https://vyos.io

Revert "docs: fix typos and grammar (ported from #1852 RST → MyST)"

2026-05-06T14:16:23+00:00

fix(ext): handle RST fallback in CmdInclude when _renderer absent

2026-05-06T13:18:42+00:00

`cmdincludemd` is in `myst_fence_as_directive`, so MyST routes fence blocks through `render_fence → render_restructuredtext → MockRSTParser`. In that path `self.state` is a plain docutils Body with no `_renderer`, crashing the RTD build. Fall back to `nested_parse` when `_renderer` is unavailable so the directive works in both MyST and RST/MockRSTParser contexts. 🤖 Generated by [robots](https://vyos.io)

Revert "Add incremental RST-to-MyST swap mechanism (circinus) (#1867)" (#1893)

2026-05-06T13:08:35+00:00

This reverts commit 5eb383a10ec92c65eed525bc174785a6852e997f.

Add incremental RST-to-MyST swap mechanism (circinus) (#1867)

2026-05-06T11:40:59+00:00

* feat(swap-circinus): add incremental RST-to-MyST swap mechanism Backport of the swap mechanism from feat/incremental-myst-swap onto the circinus release branch. Built directly on top of origin/circinus, so the underlying RST tree is circinus'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 (all from origin/myst/circinus): - 253 md-prefixed pages alongside each {name}.rst counterpart - 1 plain MyST-only page kept at canonical name (docs/copyright.md, no .rst counterpart) - 182 .webp images added (circinus release previously had only PNG/JPG; this PR brings webp into circinus alongside the originals) - docs/_swap.txt populated with all 253 stems → MyST is served by default; revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) * fix(ext): handle RST fallback in CmdInclude when _renderer absent `cmdincludemd` is in `myst_fence_as_directive`, so MyST routes fence blocks through `render_fence → render_restructuredtext → MockRSTParser`. In that path `self.state` is a plain docutils Body with no `_renderer`, crashing the RTD build. Fall back to `nested_parse` when `_renderer` is unavailable so the directive works in both MyST and RST/MockRSTParser contexts. 🤖 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) 🤖 Generated by [robots](https://vyos.io) * docs: port .readthedocs.yml jobs and swap-script tests from PR #1857 Parity backport from PR #1857 (current) — was missing on circinus. - .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. - tests/test_import_myst.py, tests/test_swap_sources.py: tests for the swap scripts. The scripts are 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(review): add conftest, filter md- from copy, fix _prefer_webp builder list, trailing newline Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/64b17346-8739-4346-b619-84438cddef21 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>

Fix T6777

2024-10-13T21:27:33+00:00

Closes https://vyos.dev/T6777 Related to https://github.com/sphinx-doc/sphinx/issues/13019 and https://github.com/orgs/sphinx-doc/discussions/13020

Fix "errror"s in docs/_ext

2024-01-17T20:51:02+00:00

include releasenotes of 1.5

2023-09-12T20:12:26+00:00

realeasenotes: change script to fix build errors

2023-04-17T19:53:04+00:00