vyos-documentation.git/docs/vpp/configuration/dataplane, branch mergify/bp/circinus/pr-2233

docs: vpp: document that kernel prerequisites need their own commit and reboot (#2233)

2026-09-17T14:23:22+00:00

* docs: vpp: document that kernel prerequisites need their own commit and reboot VPP depends on hugepages and, since T8460, on isolated CPUs. Both are configured under "system option kernel", take effect only after a reboot, and are validated by VPP against the running kernel. Because "vpp" is committed at priority 295 and "system option" at 9999, the two can never be applied in the same commit - the VPP part is always rejected with "Not enough free memory to start VPP!" or "Not enough isolated CPU cores available", both of which point back at the very command the user just issued. This is independent of the NIC: the checks that fail take no interface or PCI information and run before the NIC validation. It was reproduced both with an unsupported NIC and with a validated one. Such a commit is also partial: the "system option kernel" part is applied even though the commit is reported as failed, while the "set vpp ..." statements are discarded and have to be re-entered after the reboot. The "Optimal Configuration Example" showed exactly this failing one-shot form, mixing "set system option kernel ..." and "set vpp settings ..." in a single block. Split it into the two stages that actually work and state why, and add hugepages to it so the example covers every prerequisite. Also: * add a short "Kernel Configuration" item to the requirements page, which is what a first-time user reads and which had no pointer to the kernel settings at all * document the isolated-CPU requirement on the cpu-cores page, which did not mention "isolate-cpus" * add the missing 1af4:1041 (virtio modern ID) row to the validated NIC table - it is present in SUPPORTED_PCI_IDS but was absent here * correct the allow-unsupported-nics note, which said the check is bypassed "for the specified devices". There are no specified devices: _is_device_allowed() returns True for every interface as soon as the option is set, including interfaces attached later. That wording is a leftover from the per-PCI-ID form originally proposed in T8315, which was merged as a single boolean. Verified by building the docs; the three changed pages produce no Sphinx warnings. Claude-Session: https://claude.ai/code/session_01EQsKVSw5hhDu7jPq1YzQvj * docs: vpp: correct what a failed VPP commit leaves behind Two corrections to the pages added earlier in this PR. The partial-commit note claimed that the "set vpp ..." statements are "discarded". They are not. Verified on VyOS 2026.03: after the commit fails, "compare" still shows them staged in the configuration session. [vpp settings] + resource-allocation { + memory { + main-heap-size "6G" + } + } What actually happens is worse than the previous wording suggested and worth stating precisely: the statements are neither applied nor written by "save", because "save" writes the running configuration - which "system_option.py" has already updated with the kernel options while the VPP part was rejected. The session does not survive the reboot, so the VPP statements are lost there rather than at commit time. The isolated-CPU requirement was also described as if it only applied once "cpu-cores" is raised. It applies at the default of "cpu-cores 1" as well: verify_vpp_cpu_cores() rejects the commit whenever fewer CPUs are isolated than requested, and VPP takes its main core from the isolated set. The project's own test_01_vpp_basic relies on this - it never sets "cpu-cores" and still expects "main-core" to be taken from /sys/devices/system/cpu/isolated. Without this, a reader doing a minimal setup would conclude that CPU isolation is optional for them. Claude-Session: https://claude.ai/code/session_016gXeKHVBq2N8qRAMQkrdM6 (cherry picked from commit 93f84b050c90cb2d21d5216fc9d54fbcd118f407)

chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/

2026-05-10T14:23:58+00:00

The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio (#1899/#1900/#1901) 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 PR on rolling: yuriy/remove-rst-swap-mechanism Changes: - Move 253 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 jobs: pre_build/post_build block from .readthedocs.yml. - 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. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (267), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io)

feat: flip swap mechanism on circinus — MD as primary, RST as override

2026-05-06T18:08:17+00:00

Mirror of #1899 for circinus. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 253 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 253 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 rewritten with inverted rename direction (rst-.rst → .rst when applying overrides; .md excluded via _md_exclude.txt) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py rewritten for new semantics Identical change set to #1899 (current). Per-branch differences: - circinus has 253 stems vs current's 254 (suricata is current-only) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io

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

feat(swap-circinus): add incremental RST-to-MyST swap mechanism

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

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)

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>

vpp: T8354: Move 'ignore-kernel-routes' option out of resource-allocation section

2026-03-06T16:23:58+00:00

doc: proofread docs in /vpp/configuration/dataplane directory (#1777)

2026-03-05T10:12:18+00:00

* Initial proofread * buffers.rst * cpu.rst * index.rst * interface.rst * proofread ipsec.rst * Proofread ipv6, l2learn, lcp * Proofread remaining files in /dataplane * Fix line length lint errors