vyos-documentation.git/docs/conf.py, branch mergify/bp/circinus/pr-2341

ci: port the Cloudflare Workers docs pipeline to circinus (slug 1.5) (#2208)

2026-09-25T15:11:19+00:00

* ci: port Cloudflare Workers docs pipeline files to circinus (verbatim) Copies the branch-agnostic half of the docs.vyos.io Cloudflare Workers pipeline from `rolling` at 8cb568bf, byte-identical: - .github/workflows/docs-build.yml - workers/ (entire tree) - scripts/docs_gates/ - docker/im-convert.sh - docs/_static/js/version-picker.js, js/pagefind-wrapper.js, css/version-picker.css (new files, no circinus counterpart) - docs/_templates/breadcrumbs.html, searchbox.html (new files) docs-build.yml already triggers on push to [rolling, circinus, sagitta] and resolves `circinus` -> worker vyos-docs-v15-en / slug 1.5 from workers/matrix.json; the files simply did not exist on this branch, so slug 1.5 still serves the bootstrap placeholder. workers/versions.json + workers/matrix.json are deliberately identical across all three branches and must be kept in sync. Advances: IS-572 * ci: wire circinus docs build into the Cloudflare Workers pipeline Hand-merges the CF-specific hunks onto circinus's own docker/Dockerfile and docs/conf.py rather than clobbering them with rolling's versions — circinus keeps its own content-driven history in both files. docker/Dockerfile: - imagemagick + librsvg2-bin (sphinx.ext.imgconverter backend) and poppler-utils (pdfinfo, used by docs-build.yml's PDF page-count completeness check), installed --no-install-recommends - install docker/im-convert.sh as /usr/local/bin/im-convert docs/conf.py: - enable sphinx.ext.imgconverter + image_converter = 'im-convert' so the LaTeX/PDF builder stops silently dropping .webp/.svg images - register js/version-picker.js + css/version-picker.css unconditionally (degrades silently on ReadTheDocs) - _vyos_cf_build gate off the raw DOCS_VERSION_SLUG env var; only CF builds load js/pagefind-wrapper.js, and html_context['vyos_cf_build'] lets _templates/searchbox.html fall back to the stock Sphinx searchbox via the "!" bang-include on RTD The RTD path stays the default in both files: circinus continues building on ReadTheDocs until RTD sunset, and every CF feature activates only when DOCS_VERSION_SLUG is present. .readthedocs.yml is untouched. circinus keeps its own version/release/html_title/source_suffix and its hardcoded html_baseurl (its CF slug is also `1.5`, so rolling's DOCS_VERSION_SLUG/READTHEDOCS_VERSION resolution block is a no-op here and was deliberately not ported). Advances: IS-572 * ci: IS-572: re-sync ported Cloudflare Workers pipeline files with rolling The category-1 files in this port are byte-identical copies from `rolling`. `rolling` has since moved: [vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209) merged as `3a1c6c30`, thirteen rounds of hardening on exactly these files. Re-take all 14 category-1 paths from `origin/rolling` via `git checkout origin/rolling -- `, so byte-identity holds by construction rather than by hand-editing: .github/workflows/docs-build.yml scripts/docs_gates/{gates,parity,smoke,test_gates,test_parity,test_smoke}.py workers/.gitignore workers/apex/src/{index,special,uagate}.ts workers/apex/test/{router,uagate}.test.ts workers/apex/ua-policy.json Thirteen of the fourteen carry [vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209) exactly — the pre-change tree was byte-identical to `3a1c6c30^` for those paths. `workers/.gitignore` additionally picks up the one-line `test-results/` entry from [vyos-documentation#2212](https://github.com/vyos/vyos-documentation/pull/2212); inert on circinus, since only the deliberately-unported `apex-deploy.yml` writes that directory. Deliberate exclusions are unchanged: `docs-canary-qa.yml` (cron runs on the default branch only, so it is not ported even though [vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209) touched it on `rolling`), `apex-deploy.yml`, and the `docs-preview-*` workflows. `docs/conf.py` stays hand-merged and circinus-specific, with its ReadTheDocs fallback intact. 🤖 Generated by [robots](https://vyos.io)

docs: exclude superpowers/ from the Sphinx build (#2167)

2026-07-28T09:14:14+00:00

`docs/superpowers/` holds Claude Code plugin-generated internal design specs and plans, not user documentation. Adding `superpowers` to `exclude_patterns` guards against Sphinx ever picking the directory up and publishing it should it reappear in the source tree. Guard only — the content itself was already removed in 3ab97e71 and abb8be5b. (cherry picked from commit a9dc16aac2a7e7a6e5e4bb1c19897b3d707ba4d1) Co-authored-by: Yuriy Andamasov

T8843: Fix conflict markers committed by Mergify backport of #1994

2026-05-12T06:05:22+00:00

The auto-backport PR #1999 committed literal git conflict markers into docs/conf.py because _copy_md_sources sits before _write_llms_txt on circinus 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, line 309)". 🤖 Generated by [robots](https://vyos.io)

Fix recursive _build directory nesting error

2026-05-12T06:00:29+00:00

(cherry picked from commit ec6f33f3c256e839b443bb2baac14bff32132811) # Conflicts: # docs/conf.py

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(docs): move Cookiebot CBID to COOKIEBOT_ID env var

2026-05-07T15:23:56+00:00

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)

feat(docs): read GTM_ID from environment instead of hardcoding

2026-05-07T15:23:56+00:00

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)

Merge pull request #1879 from vyos/fix/docs-html-title-circinus

2026-05-07T07:11:48+00:00

docs(conf): set branch-localized html_title on circinus

docs(conf.py): fix stale .html reference in fail-fast comment

2026-05-07T06:48:10+00:00

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)

docs(llms.txt): update dirhtml-skip rationale after .md pivot

2026-05-07T06:40:51+00:00

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)