From 611a95401d2c5b331a97cffce9f2d4bca770ee27 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 13:13:12 +0300 Subject: docs(claude-md): add LLM-facing files + RTD layout sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backport two sections from current CLAUDE.md missing from sagitta (#1907): - LLM-Facing Files: llms.txt/llms-full.txt generation, template location. - Read the Docs Layout: full RTD slug table and html_baseurl guidance. 🤖 Generated by [robots](https://vyos.io) --- CLAUDE.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 99320758..ae0c16f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -187,6 +187,50 @@ Two valid uses: A PR that both adds and removes TODOs is not contradictory; intent matters. +## LLM-Facing Files (`llms.txt`, `llms-full.txt`) + +Both files are regenerated on every `html` and `readthedocs` builder run. +The `dirhtml` builder is intentionally skipped — production publishes +only via `html`/`readthedocs`, and we don't render llms.txt for builds +we don't ship. Local `make dirhtml` is a developer convenience and +won't emit `llms.txt`. + +Files are shipped at the docs root for each version +(`https://docs.vyos.io/en//llms.txt`, `.../llms-full.txt`). + +- **`llms-full.txt`** — auto-generated by the `sphinx_llms_txt` extension from + the full corpus. No curation; configured by `llms_txt_file = False` (which + disables the extension's *index* output, not the full output). +- **`llms.txt`** — curated overview rendered at build time from + `docs/_templates/llms.txt.j2`. URLs and the version line are interpolated + from `html_baseurl` and `release` so the file always matches the branch. + The render lives in `_write_llms_txt(app, exception)` in `docs/conf.py`, + wired via `app.connect('build-finished', ...)`. + +When adding new top-level sections to the docs, add a corresponding bullet in +`docs/_templates/llms.txt.j2`. Branch-specific differences (e.g. sagitta has +no `vpp/` or `contributing/index`) live in that branch's copy of the template. + +## Read the Docs Layout + +RTD slugs as of 2026-05-04 (verified via API): + +| Slug | Verbose | Branch | Role | +|---|---|---|---| +| `rolling` | current | `current` | canonical for rolling/next major | +| `1.5` | circinus | `circinus` | canonical for current LTS | +| `1.4` | sagitta | `sagitta` | canonical for previous LTS | +| `1.3`, `1.2` | equuleus, crux | older | canonical for older releases | + +URL-level redirect aliases (resolve to the canonicals above): +`/en/latest/* → /en/rolling/`, `/en/lts/* → /en/1.5/`, +`/en/stable/* → /en/lts/`, `/en/circinus*`, `/en/sagitta*`, +`/en/equuleus*`, `/en/crux*` → numeric slugs. + +`html_baseurl` per branch must point at the canonical (numeric or `rolling`), +not the alias, so `` and the sitemap match what RTD +serves and crawlers skip the redirect hop. + ## CI - **vyoslinter** (`doc-linter.py` from the `vyos/.github` repo, run via `lint-doc.yml`) — line length and IP rules, on changed files only. -- cgit v1.2.3 From 7a2406071a1377147c57d41d528c5436e7aec345 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 13:21:22 +0300 Subject: docs(claude-md): use exact template paths with .md extension in llms example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated by [robots](https://vyos.io) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index ae0c16f5..9a69fcd3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -209,7 +209,7 @@ Files are shipped at the docs root for each version When adding new top-level sections to the docs, add a corresponding bullet in `docs/_templates/llms.txt.j2`. Branch-specific differences (e.g. sagitta has -no `vpp/` or `contributing/index`) live in that branch's copy of the template. +no `vpp/index.md` or `contributing/index.md`) live in that branch's copy of the template. ## Read the Docs Layout -- cgit v1.2.3 From f7f7c01039a18eeff77d3bd65738df6dc8d33e39 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 13:22:52 +0300 Subject: docs(claude-md): add RTD table re-verification note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated by [robots](https://vyos.io) --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9a69fcd3..f722c509 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -213,7 +213,9 @@ no `vpp/index.md` or `contributing/index.md`) live in that branch's copy of the ## Read the Docs Layout -RTD slugs as of 2026-05-04 (verified via API): +RTD slugs as of 2026-05-04 (verified via API). Re-verify via the RTD +Versions API (project `vyos`) and update the date stamp before editing this +table. | Slug | Verbose | Branch | Role | |---|---|---|---| -- cgit v1.2.3 From 6af7602ccba33502fa703cfe776e481653e794c4 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 13:33:10 +0300 Subject: docs(claude-md): fix llms.txt backtick + consistent redirect alias patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated by [robots](https://vyos.io) --- CLAUDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f722c509..f4759273 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -191,7 +191,7 @@ A PR that both adds and removes TODOs is not contradictory; intent matters. Both files are regenerated on every `html` and `readthedocs` builder run. The `dirhtml` builder is intentionally skipped — production publishes -only via `html`/`readthedocs`, and we don't render llms.txt for builds +only via `html`/`readthedocs`, and we don't render `llms.txt` for builds we don't ship. Local `make dirhtml` is a developer convenience and won't emit `llms.txt`. @@ -226,8 +226,9 @@ table. URL-level redirect aliases (resolve to the canonicals above): `/en/latest/* → /en/rolling/`, `/en/lts/* → /en/1.5/`, -`/en/stable/* → /en/lts/`, `/en/circinus*`, `/en/sagitta*`, -`/en/equuleus*`, `/en/crux*` → numeric slugs. +`/en/stable/* → /en/lts/`, `/en/circinus/* → /en/1.5/`, +`/en/sagitta/* → /en/1.4/`, `/en/equuleus/* → /en/1.3/`, +`/en/crux/* → /en/1.2/`. `html_baseurl` per branch must point at the canonical (numeric or `rolling`), not the alias, so `` and the sitemap match what RTD -- cgit v1.2.3