summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYuriy Andamasov <yuriy@vyos.io>2026-05-06 23:13:40 +0300
committerYuriy Andamasov <yuriy@vyos.io>2026-05-06 23:13:40 +0300
commit815179aab30dd3155a7591af75684620a4d47916 (patch)
treee53b4510d16b8bd37161fded7554bf6abfae8814
parent36e66015a27cca0eabb1fdb904b47ae7c1de6101 (diff)
downloadvyos-documentation-815179aab30dd3155a7591af75684620a4d47916.tar.gz
vyos-documentation-815179aab30dd3155a7591af75684620a4d47916.zip
chore(claude-md): correct vale claim and Sphinx extension list
Three follow-up Copilot findings on the post-flip CLAUDE.md: 1. Docker image doesn't bundle vale — the repo has no `.vale.ini`, `docker/Dockerfile` doesn't install vale, and there's no Vale CI workflow. Replace the entire "Lint (vale)" section with an honest description of how linting actually happens (`vyoslinter` / `doc-linter.py` in `vyos/.github`, run by `lint-doc.yml` on changed files only). The Docker build header is updated too — it says "bundles Sphinx and the MyST/RTD plugin set" instead of the inaccurate "incl. vale". 2. `docs/_ext/releasenotes.py` and `testcoverage.py` are not Sphinx extensions — neither has a `setup()` function and neither is in `extensions = [...]` in `conf.py`. Reword the bullet so the only files described as Sphinx extensions are `vyos.py` and `autosectionlabel.py` (both registered in `extensions`); the other two are described as standalone helper scripts. Addresses Copilot review feedback on PR #1902. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io)
-rw-r--r--CLAUDE.md30
1 files changed, 13 insertions, 17 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
index f0ed81f5..5b5f6225 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,7 +11,7 @@ A small swap mechanism exists for the rare case where a maintainer needs to rend
## Build
```bash
-# Docker (recommended — bundles all deps incl. vale)
+# Docker (recommended — bundles Sphinx and the MyST/RTD plugin set)
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) \
@@ -40,19 +40,14 @@ PYTHONPATH=../scripts python -m pytest # all tests
PYTHONPATH=../scripts python -m pytest test_swap_sources.py # single file
```
-## Lint (vale)
+## Lint
-```bash
-# Lint everything
-docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
- -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
- vyos/vyos-documentation vale .
-
-# Lint a single file (substitute the real path)
-docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
- -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
- vyos/vyos-documentation vale path/to/page.rst
-```
+The repo doesn't ship a local lint config or pin a linter binary. CI runs
+`vyoslinter` (`doc-linter.py` from the `vyos/.github` repo, via the
+`lint-doc.yml` workflow) on changed files only — see the CI section
+below. For local checks, manually grep for the rules in
+[Source conventions](#source-conventions) (line length, address space,
+suppression markers).
## Branches and versions
@@ -82,10 +77,11 @@ Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR t
- `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`, `cmdincludemd`, `cfgcmdlist`, and `opcmdlist` directives plus the `cfgcmd`/`opcmd` roles 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.
+- 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.
### RST override mechanism