From e8d7e43b2c41f976bda91120242fadb8362f47e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 10:08:16 +0000 Subject: docs(agents): reflect completed MyST migration + bulk hard-wrap to 80 chars The previous README refresh sweep landed before the doc-linter was extended to MyST in 7a3aa29, so AGENTS.md was never wrapped to the 80-char rule its own 'Source conventions' section documents, and the source-format claims drifted out of sync once the RST->MyST migration finished. Content fixes (the inconsistency Copilot flagged on PR #2014): - '## Project': drop the 'MyST Markdown for migrated pages and RST for pages that haven't been migrated yet' framing. State plainly that sources are MyST Markdown only, source_suffix is ['.md'], and the RST archive under docs/_rst_legacy/ is not editable. - '### Sphinx config': source_suffix entry updated from ['.rst', '.md'] to ['.md']. - '### Source files': drop the 'docs/.rst' non-migrated bullet (no such pages exist). Add a 'docs/_include/.txt' bullet noting that the shared snippets stay RST because cmdincludemd parses their content as RST. - '**Editing rules:**': collapse 'Migrated page' / 'Non-migrated page' into one 'Existing page' rule. Add a bullet pointing at the _include/*.txt -> RST exception. - '### Command directives': rewrite to lead with MyST fenced blocks (the canonical form) and only mention RST forms for {eval-rst} blocks and _include/*.txt snippets. Avoid using literal quad-backtick code-in-code samples that would otherwise open phantom fences in the source. Linter compliance: - Hard-wrap every paragraph and bullet outside fenced code blocks to <=80 chars (~30 pre-existing violations). - Wrap the long line about the docutils inline-markup link by dropping the link entirely; the rule 'use double backticks' is self-contained and AGENTS.md doesn't need the reference. - Restructure '### Bot review workflow' table: shorten the CodeRabbit row to 79 chars and move the 'auto-reviews are disabled' note to a paragraph below the table. - Wrap the '8.8.8.8' real-public-IP bullet under '### IP addresses' with '% stop_vyoslinter' / '% start_vyoslinter' markers. The surrounding section is literally documenting suppression markers, so the meta-example reads naturally. - The '### Configuration page structure' bullet referring to MD fence syntax was using quad-backtick code-in-code; rewritten to '`{cfgcmd}` fenced code blocks (in MD)' to avoid opening a phantom fence in the linter's view of the source. --- AGENTS.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 113 insertions(+), 39 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 321f8ba5..9fa05a59 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,18 @@ # AGENTS.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +This file provides guidance to Claude Code (claude.ai/code) when working +with code in this repository. ## Project -VyOS user documentation, built with Sphinx and hosted on Read the Docs at https://docs.vyos.io. Sources are MyST Markdown (`.md`) for migrated pages and RST (`.rst`) for pages that haven't been migrated yet. Both formats are first-class to Sphinx. +VyOS user documentation, built with Sphinx and hosted on Read the Docs +at https://docs.vyos.io. Sources are MyST Markdown (`.md`) — the +migration off RST is complete, `source_suffix` in `docs/conf.py` is +`['.md']` only, and all canonical pages are `.md`. -Pre-migration RST shadows of migrated pages are archived under `docs/_rst_legacy/` for reference only — they are excluded from the build and not consulted by Sphinx. +Pre-migration RST originals are archived under `docs/_rst_legacy/` for +reference only — they are excluded from the build, not consulted by +Sphinx, and not indexed by Context7. Do not edit them. ## Build @@ -40,7 +46,8 @@ suppression markers). ## Branches and versions -One long-lived branch per VyOS release line. Branch names are constellations sorted by area: +One long-lived branch per VyOS release line. Branch names are +constellations sorted by area: | Branch | VyOS version | |--------|--------------| @@ -50,44 +57,86 @@ One long-lived branch per VyOS release line. Branch names are constellations sor | `equuleus` | 1.3.x (legacy) | | `crux` | 1.2.x (legacy) | -PRs target `rolling`. After merge, request backports via a **post-merge comment** on the PR. Multiple branches go in a single command, space-separated: +PRs target `rolling`. After merge, request backports via a **post-merge +comment** on the PR. Multiple branches go in a single command, +space-separated: ```text @Mergifyio backport circinus sagitta ``` -Only **Maintainers team members** can invoke `@Mergifyio` commands — Mergify silently drops commands from anyone outside the team (no error reply). If a backport doesn't trigger, check team membership first. Ask a Maintainer to post the comment on your behalf. +Only **Maintainers team members** can invoke `@Mergifyio` commands — +Mergify silently drops commands from anyone outside the team (no error +reply). If a backport doesn't trigger, check team membership first. Ask +a Maintainer to post the comment on your behalf. -Mergify only reads commands from **PR comments** — mentions in the PR body are ignored. -Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR template has a `## Backport` section to declare intent, but that does not trigger the backport; the comment does. +Mergify only reads commands from **PR comments** — mentions in the PR +body are ignored. +Mergify is configured at the org level (no `.mergify.yml` in the repo). +The PR template has a `## Backport` section to declare intent, but that +does not trigger the backport; the comment does. ## Architecture ### Sphinx config (`docs/conf.py`) -- `source_suffix = ['.rst', '.md']` — both formats build into the same site. +- `source_suffix = ['.md']` — Sphinx only picks up MyST Markdown + sources. The pre-migration RST originals under `docs/_rst_legacy/` + are not registered as a source extension and are excluded from the + build. - MyST extensions: `colon_fence`, `deflist`, `fieldlist`, `substitution`. -- `myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"]` — MyST fences with these names get parsed as if they were RST directives. This is how command pages stay format-portable. -- Custom modules live in `docs/_ext/` (only files listed in `extensions = [...]` in `conf.py` are actual Sphinx extensions; the others are support scripts loaded ad hoc): - - `vyos.py` (Sphinx extension, registered as `vyos`) — defines the `cfgcmd`, `opcmd`, `cmdinclude`, `cmdincludemd`, `cfgcmdlist`, `opcmdlist` directives and `cfgcmd`/`opcmd` roles that drive command coverage tracking. - - `autosectionlabel.py` (Sphinx extension, registered as `autosectionlabel`) — connects to `doctree-read` to register sections as labels. - - `testcoverage.py` — standalone helper that reads VyOS XML command definitions and exposes coverage stats; not a Sphinx extension. - - `releasenotes.py` — standalone release-notes/changelog generator script; not a Sphinx extension. +- `myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"]` — + MyST fences with these names get parsed as if they were RST + directives. This is how command pages stay format-portable. +- Custom modules live in `docs/_ext/` (only files listed in + `extensions = [...]` in `conf.py` are actual Sphinx extensions; the + others are support scripts loaded ad hoc): + - `vyos.py` (Sphinx extension, registered as `vyos`) — defines the + `cfgcmd`, `opcmd`, `cmdinclude`, `cmdincludemd`, `cfgcmdlist`, + `opcmdlist` directives and `cfgcmd`/`opcmd` roles that drive + command coverage tracking. + - `autosectionlabel.py` (Sphinx extension, registered as + `autosectionlabel`) — connects to `doctree-read` to register + sections as labels. + - `testcoverage.py` — standalone helper that reads VyOS XML command + definitions and exposes coverage stats; not a Sphinx extension. + - `releasenotes.py` — standalone release-notes/changelog generator + script; not a Sphinx extension. ### Source files -- `docs//.md` — canonical MD source for migrated pages. -- `docs/.rst` — canonical RST source for pages that have not been migrated yet (no `rst-` prefix, no MD sibling). -- `docs/_rst_legacy//rst-.rst` — archived pre-migration RST shadows. Excluded from the Sphinx build and from the Context7 index. Reference only. +- `docs//.md` — canonical MyST source for every page. + The migration off RST is complete. +- `docs/_include/.txt` — shared RST snippets included into MyST + pages via `cmdincludemd`. Their content is parsed as RST so the + legacy templates keep working unchanged. +- `docs/_rst_legacy//rst-.rst` — archived pre-migration + RST originals. Excluded from the Sphinx build and from the Context7 + index. Reference only. **Editing rules:** -- Migrated page (has `.md`): edit the `.md`. Do not touch the archived shadow under `_rst_legacy/`. -- Non-migrated page (RST-only): edit the `.rst`. -- New page: write it as `.md` from the start. The `md-` prefix that earlier MyST migration commits used is gone — never add it. + +- Existing page: edit the `.md`. Do not touch the archived original + under `_rst_legacy/`. +- New page: write it as `.md` from the start. The `md-` prefix that + earlier MyST migration commits used is gone — never add it. +- `_include/*.txt` snippets stay RST — see the next section. ### Command directives -`.. cfgcmd::`, `.. opcmd::`, and `.. cmdinclude::` are the VyOS-specific Sphinx directives in RST. They are tracked for command coverage — do **not** convert them to plain `.. code-block::`. In MyST the same directives are written as fenced blocks: ```` ```{cfgcmd} set system ... ```` (enabled by `myst_fence_as_directive`). The MyST include directive is named `cmdincludemd` (not `cmdinclude`) so that template parsing follows MyST rules in MD pages and RST rules in RST pages — pick `cmdinclude` in `.rst`, `cmdincludemd` in `.md`. +The VyOS-specific Sphinx directives are `cfgcmd`, `opcmd`, and +`cmdincludemd`. In MyST pages they are written as fenced code blocks +with `{cfgcmd}`, `{opcmd}`, or `{cmdincludemd}` as the info string +(enabled by `myst_fence_as_directive`). They are tracked for command +coverage — do **not** replace them with plain `text` or `bash` +fences. + +For RST contexts (`{eval-rst}` blocks and `_include/*.txt` snippets), +the directives are written `.. cfgcmd::`, `.. opcmd::`, and +`.. cmdinclude::`. `cmdinclude` is the RST-side include form; +`cmdincludemd` is the MyST-side form. They resolve to the same +include logic but follow the host file's parser, so pick +`cmdinclude` in `.txt`/RST contexts and `cmdincludemd` in `.md`. ## Source conventions @@ -102,15 +151,17 @@ Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR t """"" Paragraphs ``` -The first heading in every RST file uses `#` overline+underline. Field lists (e.g., `:lastproofread:`) or labels may precede it. +The first heading in every RST file uses `#` overline+underline. Field +lists (e.g., `:lastproofread:`) or labels may precede it. ### Formatting -- 80-character line limit (exception: inside `.. code-block::` / fenced code blocks — `
` preserves source verbatim).
+- 80-character line limit (exception: inside `.. code-block::` /
+  fenced code blocks — `
` preserves source verbatim).
 - American English.
 - Indent with 2 spaces.
 - Blank lines around headings.
-- Inline code: use double backticks per RST convention (the [Inline markup](https://docutils.sourceforge.io/docs/user/rst/quickref.html#inline-markup) section of the docutils quick reference).
+- Inline code: use double backticks per RST convention.
 
 ### IP addresses (linter-enforced)
 
@@ -121,11 +172,15 @@ Allowed without suppression:
 - Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0`
 
 Allowed ASN: `64496-64511` (16-bit), `65536-65551` (32-bit).
-Allowed MAC ranges: `00-53-00`–`00-53-FF` (unicast), `90-10-00`–`90-10-FF` (multicast).
+Allowed MAC ranges: `00-53-00`–`00-53-FF` (unicast),
+`90-10-00`–`90-10-FF` (multicast).
 
 **Requires `stop/start_vyoslinter` suppression:**
+
+% stop_vyoslinter
 - Real public IPs (e.g., `8.8.8.8` for DNS examples).
 - NAT64 well-known prefix `64:ff9b::/96`.
+% start_vyoslinter
 - Lines over 80 chars (URLs, certificate fingerprints).
 
 ### Linter suppression markers
@@ -140,14 +195,23 @@ Allowed MAC ranges: `00-53-00`–`00-53-FF` (unicast), `90-10-00`–`90-10-FF` (
 .. start_vyoslinter
 ```
 
-In MyST `.md` files use the comment form `% stop_vyoslinter` / `% start_vyoslinter` for top-level Markdown content. Inside `{eval-rst}` blocks (where the embedded content is parsed as RST) keep the RST form `.. stop_vyoslinter` / `.. start_vyoslinter` — the linter scans the source line literally and only the form that matches the surrounding parser is recognized. Likewise, `.txt` template files (included via `{include}` or `cmdincludemd`) keep the RST form.
+In MyST `.md` files use the comment form `% stop_vyoslinter` /
+`% start_vyoslinter` for top-level Markdown content. Inside
+`{eval-rst}` blocks (where the embedded content is parsed as RST)
+keep the RST form `.. stop_vyoslinter` / `.. start_vyoslinter` — the
+linter scans the source line literally and only the form that matches
+the surrounding parser is recognized. Likewise, `.txt` template files
+(included via `{include}` or `cmdincludemd`) keep the RST form.
 
-Markers must always come in pairs. Indentation may match the surrounding directive (indented inside a block) or sit at column 0 (top-level) — both are valid.
+Markers must always come in pairs. Indentation may match the
+surrounding directive (indented inside a block) or sit at column 0
+(top-level) — both are valid.
 
 ### Configuration page structure
 
 1. **Theory** — what it is, when to use it, relevant RFCs.
-2. **Configuration** — all CLI options as `.. cfgcmd::` (RST) or ```` ```{cfgcmd} ```` (MD).
+2. **Configuration** — all CLI options as `.. cfgcmd::` directives
+   (in RST contexts) or `{cfgcmd}` fenced code blocks (in MD).
 3. **Examples** — practical configurations with topology diagrams.
 4. **Known issues** — problems and workarounds.
 5. **Debugging** — log collection, `show` commands, state indicators.
@@ -155,8 +219,10 @@ Markers must always come in pairs. Indentation may match the surrounding directi
 ### `.. TODO::` markers
 
 Two valid uses:
-1. **Tracking** marker on pages that still need `cfgcmd`/`opcmd` conversion — intentional.
-2. **Stale** marker on pages that already have full content — should be removed.
+1. **Tracking** marker on pages that still need `cfgcmd`/`opcmd`
+   conversion — intentional.
+2. **Stale** marker on pages that already have full content — should
+   be removed.
 
 A PR that both adds and removes TODOs is not contradictory; intent matters.
 
@@ -180,9 +246,10 @@ Files are shipped at the docs root for each version
   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/index.md` or `contributing/index.md`) live in that branch's copy of the template.
+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/index.md` or `contributing/index.md`) live
+in that branch's copy of the template.
 
 ## Read the Docs Layout
 
@@ -209,8 +276,11 @@ 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.
-- **Sphinx build** — runs on Read the Docs for every PR; preview URL appears as a check.
+- **vyoslinter** (`doc-linter.py` from the `vyos/.github` repo, run
+  via `lint-doc.yml`) — line length and IP rules, on changed files
+  only.
+- **Sphinx build** — runs on Read the Docs for every PR; preview URL
+  appears as a check.
 - **CLA check** — contributors must sign the VyOS CLA before merge.
 - **Conflict check** — fails the PR if it doesn't merge cleanly into base.
 
@@ -220,13 +290,17 @@ Two bots run at separate stages — do not mix them:
 
 | Bot | When to trigger | How |
 |-----|-----------------|-----|
-| **Copilot** | **Draft PRs only** | Comment `@copilot review` |
-| **CodeRabbit** | **Ready-for-review PRs only** | Comment `@coderabbitai review` (auto-reviews are disabled on this repo) |
+| **Copilot** | Draft PRs only | Comment `@copilot review` |
+| **CodeRabbit** | Ready-for-review PRs only | Comment `@coderabbitai review` |
+
+Auto-reviews are disabled on this repo — both bots are triggered
+manually via the comments shown above.
 
 Workflow:
 1. Open PR as draft (`gh pr create --draft`).
 2. Iterate; when complete, comment `@copilot review`.
-3. Address Copilot threads, re-request after each fix round until Copilot is silent.
+3. Address Copilot threads, re-request after each fix round until
+   Copilot is silent.
 4. Flip to ready (`gh pr ready `), then comment `@coderabbitai review`.
 5. Address CodeRabbit threads the same way.
 
-- 
cgit v1.2.3