From 038b3a3a2ad91f67f074ba05a35d800c3dac2c07 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Sat, 2 May 2026 21:13:13 +0300
Subject: feat(swap-circinus): add incremental RST-to-MyST swap mechanism
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backport of the swap mechanism from feat/incremental-myst-swap onto
the circinus release branch. Built directly on top of origin/circinus,
so the underlying RST tree is circinus's (not current's).

Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
  Sphinx builds, restore after; writes _build/_swap_state.json and
  _build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
  trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
  loader; _prefer_webp builder hook so html prefers webp over png

Content (all from origin/myst/circinus):
- 253 md-prefixed pages alongside each {name}.rst counterpart
- 1 plain MyST-only page kept at canonical name (docs/copyright.md,
  no .rst counterpart)
- 182 .webp images added (circinus release previously had only
  PNG/JPG; this PR brings webp into circinus alongside the originals)
- docs/_swap.txt populated with all 253 stems → MyST is served by
  default; revert a page by removing its stem from _swap.txt

🤖 Generated by [robots](https://vyos.io)
---
 docs/Makefile | 40 ++++++++++++++++++++++++++++++----------
 1 file changed, 30 insertions(+), 10 deletions(-)

(limited to 'docs/Makefile')

diff --git a/docs/Makefile b/docs/Makefile
index cb6226af..29ef3906 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,22 +12,42 @@ AUTOHOST      = 0.0.0.0
 AUTOPORT      = 8000
 AUTOOPTS      = --watch .
 
+SWAP          = python3 ../scripts/swap_sources.py
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+swap:
+	$(SWAP) --swap
 
-livehtml:
-	sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \
-		"$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+restore:
+	$(SWAP) --restore
+
+html: swap
+	@trap '$(SWAP) --restore' EXIT; \
+		$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+dirhtml: swap
+	@trap '$(SWAP) --restore' EXIT; \
+		$(SPHINXBUILD) -M dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+pdf: swap
+	@trap '$(SWAP) --restore' EXIT; \
+		$(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml: swap
+	@trap '$(SWAP) --restore' EXIT; \
+		sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) \
+		--ignore '$(BUILDDIR)/**' \
+		"$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 defaultvalue: export VYOS_DEFAULT=True
-defaultvalue:	
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+defaultvalue: html
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-- 
cgit v1.2.3