From f1298c8b35b9a2e1a0d5352a6fb687129bcb56eb Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 22:14:53 +0300 Subject: chore(claude-md): update for post-flip MyST-as-primary state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLAUDE.md scaffolded by /init reflected the pre-MyST repo and was never updated as the migration landed. Replaces it with a current description of how the repo actually works: - MD is the canonical source for migrated pages on all three release branches (current/circinus/sagitta) as of 2026-05-06. RST is the canonical source for pages that haven't been migrated yet. - Documents the rare RST override mechanism: rst-.rst plus docs/_rst_overrides.txt, scripts/swap_sources.py CLI flags. The override list is empty by default; the mechanism is a no-op. - Editing rules: edit the .md for migrated pages, the .rst for non-migrated pages, write new pages as .md from the start. The md- prefix used during the migration is gone. Also adds previously-missing sections: tests command, vale lint command, branches/versions table with constellation→version mapping, PR review flow with Copilot+CodeRabbit, worktree convention. Generated by robots https://vyos.io --- CLAUDE.md | 193 +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 128 insertions(+), 65 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 60f7d13f..2d553780 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,81 +1,147 @@ -# VyOS Documentation +# CLAUDE.md -RST documentation for VyOS, built with Sphinx and hosted on Read the Docs. +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 the rest. Both formats are first-class to Sphinx; MD is the canonical source for any page that has been migrated, and RST is the canonical source for pages that haven't. + +A small swap mechanism exists for the rare case where a maintainer needs to render the legacy RST version of a page that already has an MD primary — see `RST override mechanism` below. The override list is empty by default. ## Build ```bash -# Docker (recommended) +# Docker (recommended — bundles all deps incl. vale) docker build -t vyos/vyos-documentation docker docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ vyos/vyos-documentation make html -# Local +# Live-reload server on port 8000 +docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-documentation make livehtml + +# Local (Python 3, see requirements.txt for pinned versions) pip install -r requirements.txt cd docs && make html ``` -Output goes to `docs/_build/html/`. +Output: `docs/_build/html/`. -## RST Conventions +## Tests -### Heading Hierarchy +```bash +pytest tests/ # all tests +pytest tests/test_swap_sources.py # single test file +``` -```rst -##### -Title -##### +## Lint (vale) -******** -Chapters -******** +```bash +docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-documentation vale . # all files +docker run ... vale path/to/page.rst # single file +``` + +## Branches and versions -Sections -======== +One long-lived branch per VyOS release line. Branch names are constellations sorted by area: -Subsections ------------ +| Branch | VyOS version | +|--------|--------------| +| `current` | rolling / 1.5+ (default branch — all new docs target this) | +| `circinus` | 1.5.x | +| `sagitta` | 1.4.x | +| `equuleus` | 1.3.x (legacy) | +| `crux` | 1.2.x (legacy) | -Subsubsections -^^^^^^^^^^^^^^ +PRs target `current`. After merge, request backports via Mergify comments on the PR: -Paragraphs -"""""""""" ``` +@Mergifyio backport circinus +@Mergifyio backport sagitta +``` + +Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR template has a `## Backport` section to declare intent. + +## Architecture + +### Sphinx config (`docs/conf.py`) -The first heading in every RST file must use `#` overline+underline. Files may have field lists (e.g., `:lastproofread:`) or labels before the heading. +- `source_suffix = ['.rst', '.md']` — both formats build into the same site. +- 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 Sphinx extensions live in `docs/_ext/`: + - `vyos.py` — defines the `cfgcmd`, `opcmd`, `cmdinclude` directives that drive command coverage tracking. + - `testcoverage.py` — reads VyOS XML command definitions and exposes coverage stats. + - `releasenotes.py`, `autosectionlabel.py` — release-notes builder and label-prefix tweak. -### Formatting Rules +### RST override mechanism -- 80 character line limit (except inside `.. code-block::`) -- American English -- Indent with 2 spaces -- Leave a blank line before and after headers -- Use double backticks for inline code: ``` ``command`` ``` -- Use `.. code-block:: none` for command/output blocks +For pages that have been migrated from RST to MyST: -### Address Space +- `docs/.md` — canonical MD source (primary). +- `docs/rst-.rst` — preserved RST sibling kept around as an override option, prefixed `rst-` so it doesn't collide with the MD. Excluded from the build by `exclude_patterns` in `conf.py`. +- `docs/_rst_overrides.txt` — list of page stems that should render from `rst-.rst` instead of `.md`. Empty by default; pages listed here have their RST temporarily activated for the build. +- `scripts/swap_sources.py` — CLI for `--swap` (apply overrides), `--restore`, `--dry-run`, `--status`. Build-time state lands in `docs/_build/_rst_override_state.json` and `docs/_build/_md_exclude.txt` (gitignored). -See `docs/documentation.rst` for canonical rules. Per RFC 5737, RFC 3849, RFC 5389, and RFC 7042: +For pages that have NOT been migrated: -The linter enforces documentation-reserved addresses. Use only: +- `docs/.rst` — original RST, no `rst-` prefix, no MD sibling. -- IPv4: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` -- IPv6: `2001:db8::/32` -- ASN: `64496-64511` (16-bit), `65536-65551` (32-bit) -- MAC: `00-53-00` to `00-53-FF` (unicast), `90-10-00` to `90-10-FF` (multicast) +**Editing rules:** +- Migrated page (has `.md`): edit the `.md`. Don't touch `rst-.rst` unless you're maintaining a parallel RST version that someone has flagged in `_rst_overrides.txt`. +- 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. -**Allowed without suppression:** +Running `make html` runs the swap automatically (it's a no-op when the override list is empty, which is the default state). + +### Command directives + +`.. cfgcmd::`, `.. opcmd::`, and `.. cmdinclude::` are the VyOS-specific Sphinx directives. 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 ... ` (the `myst_fence_as_directive` config makes this work). + +## Source conventions + +### RST heading hierarchy + +``` +##### Title (overline+underline, one per file) +***** Chapters +===== Sections +----- Subsections +^^^^^ Subsubsections +""""" Paragraphs +``` + +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).
+- American English.
+- Indent with 2 spaces.
+- Blank lines around headings.
+- Inline code: `` ``command`` ``.
+
+### IP addresses (linter-enforced)
+
+Allowed without suppression:
+- RFC 5737 IPv4 docs: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`
+- RFC 3849 IPv6 docs: `2001:db8::/32`
 - RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
-- Link-local, loopback, and other non-public ranges
+- Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0`
 
-**Requires `stop/start_vyoslinter`:**
-- Real public IPs when needed for authenticity (e.g., `8.8.8.8` in DNS examples)
-- NAT64 well-known prefix `64:ff9b::/96`
-- Long URLs or certificate fingerprints that exceed 80 chars
+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).
 
-### Linter Suppression
+**Requires `stop/start_vyoslinter` suppression:**
+- Real public IPs (e.g., `8.8.8.8` for DNS examples).
+- NAT64 well-known prefix `64:ff9b::/96`.
+- Lines over 80 chars (URLs, certificate fingerprints).
+
+### Linter suppression markers
 
 ```rst
 .. stop_vyoslinter
@@ -87,32 +153,29 @@ The linter enforces documentation-reserved addresses. Use only:
 .. start_vyoslinter
 ```
 
-Place markers immediately before/after the block they suppress. Always re-enable with `start_vyoslinter`.
-
-### VyOS-Specific Directives
+In MyST `.md` files use the comment form: `% stop_vyoslinter` / `% start_vyoslinter`. In `.txt` template files (included via `{include}` or `cmdincludemd`) keep the RST form: `.. stop_vyoslinter` / `.. start_vyoslinter`.
 
-- `.. cfgcmd::` — configuration mode commands
-- `.. opcmd::` — operational mode commands
-- `.. cmdinclude::` — include command definitions from XML
+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.
 
-### Page Structure
+### Configuration page structure
 
-Each configuration page should contain:
+1. **Theory** — what it is, when to use it, relevant RFCs.
+2. **Configuration** — all CLI options as `.. cfgcmd::` (RST) or ` ```{cfgcmd} ` (MD).
+3. **Examples** — practical configurations with topology diagrams.
+4. **Known issues** — problems and workarounds.
+5. **Debugging** — log collection, `show` commands, state indicators.
 
-1. **Theory** — what it is, when to use it, relevant RFCs
-2. **Configuration** — all CLI options with `.. cfgcmd::` directives
-3. **Examples** — practical configurations with topology diagrams
-4. **Known issues** — problems and workarounds
-5. **Debugging** — log collection, `show` commands, state indicators
+### `.. TODO::` markers
 
-## CI
+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.
 
-- **Linter** (`doc-linter.py` from `vyos/.github`): checks line length and IP addresses on changed files only
-- **Sphinx build**: runs on Read the Docs for each PR
-- **CLA check**: contributors must sign the CLA
+A PR that both adds and removes TODOs is not contradictory; intent matters.
 
-## Git Workflow
+## CI
 
-- Base branch: `current`
-- Branch naming: `fix/docs-*`, `feat/docs-*`
-- PRs target `current` branch
+- **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.
-- 
cgit v1.2.3