From 88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 18:46:21 +0300 Subject: feat: import MyST swap mechanism + content for sagitta (replaces #1886) Replaces the broken #1886 with a fresh, properly-converted MyST set for the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897. This PR: - Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc fallback) on sagittas RST. Post-processed via the pipelines postprocess stage (10 ordered fixes for blanks, admonitions, label hyphens, pandoc artifacts, structural blanks, linter markers). Compared to the broken #1886 content (which was left over from an earlier stage-1-only run): zero raw `
` remnants. - For 23 stems where sagittas RST is byte-identical with currents RST (mostly stable policy/protocol pages and the 404 page), reuses currents already-validated md-*.md content rather than re-converting. - Drops cli and installation/cloud/aws from sagittas swap set: their RST has SEVERE/4 "Title level inconsistent" errors that crash rst-to-myst; they need an independent RST-source fix and are kept as RST-only for now. - Adds the per-page swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, the matching tests under tests/, _swap.txt with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile swap-wrapped targets, .readthedocs.yml swap pre/post hooks. - Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg static assets; flips html_logo to vyos-logo.webp. - Adds the MyST swap-related blocks to docs/conf.py only: myst_enable_extensions, myst_fence_as_directive, md-*.md exclude patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources setup hooks. github_version fallback set to 'sagitta' to match the branch (parallel to currents 'current' and circinuss 'circinus'). Deliberately excluded (per user direction): - llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will land separately for sagitta via #1870 plus a new sagitta-specific llms.txt template PR. The conf.py here does not pull those extensions in, so the build does not depend on the new pip packages. Verification before pushing: - 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1). - 0 files contain raw `
` as +a deamonless container engine. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set container name image + + Sets the image name in the hub registry + + .. code-block:: none + + set container name mysql-server image mysql:8.0 + + If a registry is not specified, Docker.io will be used as the container + registry unless an alternative registry is specified using + **set container registry ** or the registry is included + in the image name + + .. code-block:: none + + set container name mysql-server image quay.io/mysql:8.0 +``` + +```{eval-rst} +.. cfgcmd:: set container name entrypoint + + Override the default entrypoint from the image for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name command + + Override the default command from the image for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name arguments + + Set the command arguments for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name host-name + + Set the host name for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name allow-host-pid + + The container and the host share the same process namespace. + This means that processes running on the host are visible inside the + container, and processes inside the container are visible on the host. + + The command translates to "--pid host" when the container is created. +``` + +```{eval-rst} +.. cfgcmd:: set container name allow-host-networks + + Allow host networking in a container. The network stack of the container is + not isolated from the host and will use the host IP. + + The command translates to "--net host" when the container is created. + + .. note:: **allow-host-networks** cannot be used with **network** +``` + +```{eval-rst} +.. cfgcmd:: set container name network + + Attaches user-defined network to a container. + Only one network must be specified and must already exist. +``` + +```{eval-rst} +.. cfgcmd:: set container name network address
+ + Optionally set a specific static IPv4 or IPv6 address for the container. + This address must be within the named network prefix. + + .. note:: The first IP in the container network is reserved by the + engine and cannot be used +``` + +```{eval-rst} +.. cfgcmd:: set container name description + + Set a container description +``` + +```{eval-rst} +.. cfgcmd:: set container name environment value + + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the container + is created. + + .. code-block:: none + + set container name mysql-server environment MYSQL_DATABASE value 'zabbix' + set container name mysql-server environment MYSQL_USER value 'zabbix' + set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' + set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' +``` + +```{eval-rst} +.. cfgcmd:: set container name port source +``` + +```{eval-rst} +.. cfgcmd:: set container name port destination +``` + +```{eval-rst} +.. cfgcmd:: set container name port protocol + + Publish a port for the container. + + .. code-block:: none + + set container name zabbix-web-nginx-mysql port http source 80 + set container name zabbix-web-nginx-mysql port http destination 8080 + set container name zabbix-web-nginx-mysql port http protocol tcp +``` + +```{eval-rst} +.. cfgcmd:: set container name volume source +``` + +```{eval-rst} +.. cfgcmd:: set container name volume destination + + Mount a volume into the container + + .. code-block:: none + + set container name coredns volume 'corefile' source /config/coredns/Corefile + set container name coredns volume 'corefile' destination /etc/Corefile +``` + +```{eval-rst} +.. cfgcmd:: set container name volume mode + + Volume is either mounted as rw (read-write - default) or ro (read-only) +``` + +```{eval-rst} +.. cfgcmd:: set container name uid +``` + +```{eval-rst} +.. cfgcmd:: set container name gid + + Set the User ID or Group ID of the container +``` + +```{eval-rst} +.. cfgcmd:: set container name restart [no | on-failure | always] + + Set the restart behavior of the container. + + - **no**: Do not restart containers on exit + - **on-failure**: Restart containers when they exit with a non-zero + exit code, retrying indefinitely (default) + - **always**: Restart containers when they exit, regardless of status, + retrying indefinitely +``` + +```{eval-rst} +.. cfgcmd:: set container name cpu-quota + + This specifies the number of CPU resources the container can use. + + Default is 0 for unlimited. + For example, 1.25 limits the container to use up to 1.25 cores + worth of CPU time. + This can be a decimal number with up to three decimal places. + + The command translates to "--cpus=" when the container is created. +``` + +```{eval-rst} +.. cfgcmd:: set container name memory + + Constrain the memory available to the container. + + Default is 512 MB. Use 0 MB for unlimited memory. +``` + +```{eval-rst} +.. cfgcmd:: set container name device source +``` + +```{eval-rst} +.. cfgcmd:: set container name device destination + + Add a host device to the container. +``` + +```{eval-rst} +.. cfgcmd:: set container name capability + + Set container capabilities or permissions. + + - **net-admin**: Network operations (interface, firewall, routing tables) + - **net-bind-service**: Bind a socket to privileged ports + (port numbers less than 1024) + - **net-raw**: Permission to create raw network sockets + - **setpcap**: Capability sets (from bounded or inherited set) + - **sys-admin**: Administration operations (quotactl, mount, sethostname, + setdomainame) + - **sys-time**: Permission to set system clock +``` + +```{eval-rst} +.. cfgcmd:: set container name sysctl parameter value + + Set container sysctl values. + + The subset of possible parameters are: + + - Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, + kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + - Parameters beginning with fs.mqueue.* + - Parameters beginning with net.* (only if user-defined network is used) +``` + +```{eval-rst} +.. cfgcmd:: set container name label