diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 23:13:40 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 23:13:40 +0300 |
| commit | 815179aab30dd3155a7591af75684620a4d47916 (patch) | |
| tree | e53b4510d16b8bd37161fded7554bf6abfae8814 | |
| parent | 36e66015a27cca0eabb1fdb904b47ae7c1de6101 (diff) | |
| download | vyos-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.md | 30 |
1 files changed, 13 insertions, 17 deletions
@@ -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 |
