From 6b02343f9cbb1295875c067159cb8a764abbf433 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 14 May 2026 00:04:10 +0300 Subject: docs: refresh README + AGENTS source-format claim for sagitta MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adapted from PR #2014 on rolling, tailored to this branch's actual state. This branch (sagitta, 1.4.x previous LTS) is migrated to MyST Markdown 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. Changes: - README.md: new `## Source format` section naming the two stuck RST pages, pointing at the `_rst_legacy/` archive, and noting the MyST-fence form for VyOS command directives in .md pages. The `## Contributing` blurb drops the now-imprecise "MyST for migrated pages, RST for the rest" phrasing. - AGENTS.md: `## Project` and `### Source files` sections updated to name the two remaining RST pages explicitly so contributors know which files are still RST and which to write as MyST. Linter origin claim ("doc-linter.py from the vyos/.github repo") left intact — that script is NOT inlined on this branch. 🤖 Generated by [robots](https://vyos.io) --- AGENTS.md | 15 ++++++++------- README.md | 23 ++++++++++++++++++++--- 2 files changed, 28 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 923beae9..d0ecd16e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//.md` — canonical MD source for migrated pages. -- `docs/.rst` — canonical RST source for pages that have not been migrated yet (no `rst-` prefix, no MD sibling). -- `docs/_rst_legacy//rst-.rst` — archived pre-migration RST shadows. Excluded from the Sphinx build and from the Context7 index. Reference only. +- `docs//.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/.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//rst-.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 `.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 `.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 diff --git a/README.md b/README.md index 290c6ce1..daed740d 100644 --- a/README.md +++ b/README.md @@ -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. -- cgit v1.2.3