diff options
| -rw-r--r-- | AGENTS.md | 15 | ||||
| -rw-r--r-- | README.md | 23 |
2 files changed, 28 insertions, 10 deletions
@@ -4,9 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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. This branch (`sagitta`, 1.4.x previous LTS) is migrated to MyST Markdown (`.md`) except for two pages with known converter issues that stayed in RST: `docs/cli.rst` and `docs/installation/cloud/aws.rst`. `source_suffix` in `docs/conf.py` is `['.rst', '.md']`. Both formats are first-class to Sphinx. -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 shadows of converted pages are archived under `docs/_rst_legacy/` for reference only — they are excluded from the build, not consulted by Sphinx, and must not be edited. ## Build @@ -74,13 +74,14 @@ Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR t ### Source files -- `docs/<subdir>/<page>.md` — canonical MD source for migrated pages. -- `docs/<page>.rst` — canonical RST source for pages that have not been migrated yet (no `rst-` prefix, no MD sibling). -- `docs/_rst_legacy/<subdir>/rst-<page>.rst` — archived pre-migration RST shadows. Excluded from the Sphinx build and from the Context7 index. Reference only. +- `docs/<subdir>/<page>.md` — canonical MD source for migrated pages (most of the tree). +- The two RST-only pages on this branch: `docs/cli.rst` and `docs/installation/cloud/aws.rst`. Both stayed RST due to converter issues at MyST-migration time and have not been revisited since. +- `docs/_include/<name>.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/<subdir>/rst-<page>.rst` — archived pre-migration RST shadows of converted pages. Excluded from the Sphinx build and from the Context7 index. Reference only. **Editing rules:** -- Migrated page (has `<page>.md`): edit the `.md`. Do not touch the archived shadow under `_rst_legacy/`. -- Non-migrated page (RST-only): edit the `.rst`. +- Existing migrated page (has `<page>.md`): edit the `.md`. Do not touch the archived shadow under `_rst_legacy/`. +- One of the two remaining RST-only pages above: 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. ### Command directives @@ -8,6 +8,23 @@ https://docs.vyos.io. The earlier wiki for VyOS 1.1.x and pre-1.2.0 docs is preserved on the [Wayback Machine](https://web.archive.org/web/20200225171529/https://wiki.vyos.net/wiki/Main_Page). +## Source format + +This branch (`sagitta`, 1.4.x previous LTS) is migrated to +[MyST Markdown](https://myst-parser.readthedocs.io/) (`.md`) except +for two pages with known converter issues that stayed in RST: +`docs/cli.rst` and `docs/installation/cloud/aws.rst`. `source_suffix` +in `docs/conf.py` is `['.rst', '.md']` to cover both. The +pre-migration RST shadows of converted pages are archived under +`docs/_rst_legacy/` for reference; they are excluded from the build +and must not be edited. + +VyOS-specific command directives (`cfgcmd`, `opcmd`, `cmdincludemd`) +are written as MyST fenced blocks in `.md` pages +(`myst_fence_as_directive` in `conf.py`) and as the RST forms +`.. cfgcmd::` / `.. opcmd::` / `.. cmdinclude::` in the two +remaining `.rst` pages and in shared `_include/*.txt` snippets. + ## Branches The documentation repository tracks the same branch convention as the VyOS @@ -60,6 +77,6 @@ Output lands in `docs/_build/html/`. ## Contributing -See [AGENTS.md](AGENTS.md) for the full contributor guide — source format -conventions (MyST Markdown for migrated pages, RST for the rest), CLI -directive syntax, IP-address rules, the linter, and the bot review workflow. +See [AGENTS.md](AGENTS.md) for the full contributor guide — MyST +conventions, CLI directive syntax, IP-address rules, linter +suppression markers, and the Copilot / CodeRabbit bot workflow. |