diff options
| -rw-r--r-- | .github/copilot-instructions.md | 68 | ||||
| -rw-r--r-- | .github/instructions/rst-linter.instructions.md | 70 | ||||
| -rw-r--r-- | CLAUDE.md | 118 |
3 files changed, 256 insertions, 0 deletions
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..dd18e7e6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,68 @@ +## VyOS Documentation Project + +This is VyOS user documentation written in reStructuredText (RST) and built with Sphinx. + +### Review Scope + +When reviewing pull requests, only flag issues **introduced by the PR's changes**. Do not flag pre-existing issues in unchanged lines. Compare against the base branch to determine what was actually changed. + +### RST Heading Hierarchy + +All files must use this heading order: + +``` +##### (Title — one per file, with overline) +***** (Chapters) +===== (Sections) +----- (Subsections) +^^^^^ (Subsubsections) +""""" (Paragraphs) +``` + +### Line Length + +Maximum 80 characters per line. Exception: content inside `.. code-block::` directives is **exempt** — they render with `<pre>` tags and preserve source formatting. Do not flag long lines inside code blocks. + +### Linter Suppression Markers + +`.. stop_vyoslinter` and `.. start_vyoslinter` are RST comments used to suppress CI linter checks. Key conventions: + +- When used **inside an indented directive** (`.. cfgcmd::`, `.. opcmd::`, list items), markers should match the surrounding indentation to stay within the block. +- When used **at top level** (outside any directive), markers are placed at column 0. +- Both patterns exist in this repo. Do not flag either placement as incorrect. +- They must always appear in pairs (stop then start). A missing `start_vyoslinter` is a real issue. +- A `stop_vyoslinter` that covers a large section is acceptable when the content requires it (e.g., files full of real debug output with production IPs). + +### IP Address Rules + +The CI linter checks IP addresses. These are **allowed without suppression** — do not flag them: + +- RFC 5737 documentation addresses: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` +- RFC 3849 documentation IPv6: `2001:db8::/32` +- RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` +- Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0` + +Real public IPs (e.g., `8.8.8.8`) require `stop/start_vyoslinter` suppression. Do not suggest replacing them with documentation addresses if the example intentionally uses real IPs. + +### TODO Markers + +`.. TODO::` directives serve two purposes in this repo: + +1. **Tracking markers** on pages that need `cfgcmd`/`opcmd` conversion (these are intentionally added). +2. **Stale markers** on pages that already have full content (these should be removed). + +A PR that removes some TODOs and adds others is not contradictory — the intent matters. + +### VyOS Directives + +- `.. cfgcmd::` for configuration mode commands +- `.. opcmd::` for operational mode commands +- Do not convert these to plain `.. code-block::` — they are tracked for command coverage. + +### YAML in Code Blocks + +Ansible playbook examples in `.. code-block::` use RST indentation (typically 4 spaces from the directive). The YAML indentation within the block may differ from standalone YAML files. Verify carefully before flagging YAML as invalid — count spaces from the code-block's own indentation base, not from column 0. + +### Page Structure + +Configuration pages follow this order: Theory, Configuration (cfgcmd), Examples, Known Issues, Debugging. diff --git a/.github/instructions/rst-linter.instructions.md b/.github/instructions/rst-linter.instructions.md new file mode 100644 index 00000000..419f094a --- /dev/null +++ b/.github/instructions/rst-linter.instructions.md @@ -0,0 +1,70 @@ +--- +applyTo: "**/*.rst" +--- + +## RST Linter Rules + +Every pull request is automatically linted by `doc-linter.py` (from the `vyos/.github` repository). It checks **only changed files** for two things: IP address usage and line length. + +### IP Address Rules + +The linter rejects public IP addresses that are not reserved for documentation. + +**Use these documentation-reserved addresses (no suppression needed):** + +| Type | Range | RFC | +|------|-------|-----| +| IPv4 | `192.0.2.0/24` (TEST-NET-1) | RFC 5737 | +| IPv4 | `198.51.100.0/24` (TEST-NET-2) | RFC 5737 | +| IPv4 | `203.0.113.0/24` (TEST-NET-3) | RFC 5737 | +| IPv6 | `2001:db8::/32` | RFC 3849 | + +**These are allowed without suppression (not flagged by linter):** + +| Type | Range | Why | +|------|-------|-----| +| RFC 1918 private | `10.0.0.0/8` | Private address space | +| RFC 1918 private | `172.16.0.0/12` | Private address space | +| RFC 1918 private | `192.168.0.0/16` | Private address space | +| Loopback | `127.0.0.0/8` | Loopback range | +| Link-local | `169.254.0.0/16` | Link-local | + +**These require `stop/start_vyoslinter` suppression:** + +| Example | Why suppression is needed | +|---------|--------------------------| +| `8.8.8.8` (Google DNS) | Real public IP, not documentation-reserved | +| `64:ff9b::/96` (NAT64) | Well-known prefix, not in doc ranges | +| Real provider IPs in examples | Authenticity matters for the example | + +### Line Length Rules + +Maximum 80 characters per line. Lines inside `.. code-block::` directives are **exempt** from the line length limit (they render with `<pre>` tags and preserve source formatting). + +### Suppression Syntax + +When real public IPs or long lines are unavoidable, wrap the block: + +```rst +.. stop_vyoslinter + +.. code-block:: none + + set system name-server '8.8.8.8' + +.. start_vyoslinter +``` + +**Rules for suppression markers:** + +- Place `.. stop_vyoslinter` on its own line, immediately before the content +- Place `.. start_vyoslinter` on its own line, immediately after the content +- Always re-enable the linter — never leave it stopped for the rest of the file +- Suppress the smallest possible region +- Do NOT use suppression for content that can use documentation-reserved addresses instead + +### Common Mistakes + +- Removing `stop/start_vyoslinter` markers without fixing the underlying issue (exposes the line to the linter and fails CI) +- Using real public IPs when documentation addresses would work just as well +- Adding suppression markers around content that only has private (RFC 1918) addresses or `0.0.0.0/0` — these are allowed and don't need suppression diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..d5330e0b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,118 @@ +# VyOS Documentation + +RST documentation for VyOS, built with Sphinx and hosted on Read the Docs. + +## Build + +```bash +# Docker (recommended) +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 (run from docs/ directory) +pip install -r requirements.txt +cd docs && make html +``` + +Output goes to `docs/_build/html/`. + +## RST Conventions + +### Heading Hierarchy + +```rst +##### +Title +##### + +******** +Chapters +******** + +Sections +======== + +Subsections +----------- + +Subsubsections +^^^^^^^^^^^^^^ + +Paragraphs +"""""""""" +``` + +Every RST file must start with a `#` overline+underline title. + +### Formatting Rules + +- 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 + +### Address Space + +See `docs/documentation.rst` for canonical rules. Per RFC 5737, RFC 3849, RFC 5389, and RFC 7042: + +The linter enforces documentation-reserved addresses. Use only: + +- 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) + +**Allowed without suppression:** +- 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 + +**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 + +### Linter Suppression + +```rst +.. stop_vyoslinter + +.. code-block:: none + + content with real IPs or long lines here + +.. start_vyoslinter +``` + +Place markers immediately before/after the block they suppress. Always re-enable with `start_vyoslinter`. + +### VyOS-Specific Directives + +- `.. cfgcmd::` — configuration mode commands +- `.. opcmd::` — operational mode commands +- `.. cmdinclude::` — include command definitions from XML + +### Page Structure + +Each configuration page should contain: + +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 + +## CI + +- **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 + +## Git Workflow + +- Base branch: `current` +- Branch naming: `fix/docs-*`, `feat/docs-*` +- PRs target `current` branch |