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