Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)

* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism

Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta'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:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
  alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
  (already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
  PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
  default, revert a page by removing its stem from _swap.txt

🤖 Generated by [robots](https://vyos.io)

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

🤖 Generated by [robots](https://vyos.io)

* docs: address review feedback (backport from PR #1857)

Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.

🤖 Generated by [robots](https://vyos.io)

* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857

Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.

- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
  scripts/swap_sources.py --swap before the Sphinx build and --restore
  after. Without this, the swap mechanism ships but never runs on RTD
  builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
  when self.state._renderer is not present. Required for cfgcmd /
  opcmd / cmdincludemd directives to render correctly when included
  from MyST pages (the swap mechanism's whole point). Sagitta-only
  delta on _ext/vyos.py (the path = str(path) line on 224) is
  intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
  swap scripts. The scripts on this branch are byte-identical to
  current's, so the same tests apply. Travels with the branch so CI
  catches per-branch regressions if the scripts ever drift.

🤖 Generated by [robots](https://vyos.io)

* fix(conf): skip md-*.md staging files in _copy_md_sources

Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc

Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

1 files changed, 122 insertions, 0 deletions

diff --git a/docs/configuration/service/md-https.md b/docs/configuration/service/md-https.md
new file mode 100644
index 00000000..e68bcd50
--- /dev/null
+++ b/docs/configuration/service/md-https.md
@@ -0,0 +1,122 @@
+# HTTP API
+
+VyOS provide an HTTP API. You can use it to execute op-mode commands,
+update VyOS, set or delete config.
+
+Please take a look at the `vyosapi` page for an detailed how-to.
+
+## Configuration
+
+<div class="cfgcmd">
+
+set service https allow-client address \<address\>
+
+Only allow certain IP addresses or prefixes to access the https
+webserver.
+
+</div>
+
+<div class="cfgcmd">
+
+set service https certificates ca-certificate \<name\>
+
+Use CA certificate from PKI subsystem
+
+</div>
+
+<div class="cfgcmd">
+
+set service https certificates certificate \<name\>
+
+Use certificate from PKI subsystem
+
+</div>
+
+<div class="cfgcmd">
+
+set service https certificates dh-params \<name\>
+
+Use `DH (Diffie–Hellman)` parameters from PKI subsystem.
+Must be at least 2048 bits in length.
+
+</div>
+
+<div class="cfgcmd">
+
+set service https listen-address \<address\>
+
+Webserver should only listen on specified IP address
+
+</div>
+
+<div class="cfgcmd">
+
+set service https port \<number\>
+
+Webserver should listen on specified port.
+
+Default: 443
+
+</div>
+
+<div class="cfgcmd">
+
+set service https enable-http-redirect
+
+Enable automatic redirect from http to https.
+
+</div>
+
+<div class="cfgcmd">
+
+set service https tls-version \<1.2 | 1.3\>
+
+Select TLS version used.
+
+This defaults to both 1.2 and 1.3.
+
+</div>
+
+<div class="cfgcmd">
+
+set service https vrf \<name\>
+
+Start Webserver in given VRF.
+
+</div>
+
+### API
+
+<div class="cfgcmd">
+
+set service https api keys id \<name\> key \<apikey\>
+
+Set a named api key. Every key has the same, full permissions
+on the system.
+
+</div>
+
+<div class="cfgcmd">
+
+set service https api debug
+
+To enable debug messages. Available via `show log` or
+`monitor log`
+
+</div>
+
+<div class="cfgcmd">
+
+set service https api strict
+
+Enforce strict path checking
+
+</div>
+
+## Example Configuration
+
+Set an API-KEY is the minimal configuration to get a working API Endpoint.
+
+``` none
+set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
+```