feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 0 insertions, 442 deletions

diff --git a/docs/md-documentation.md b/docs/md-documentation.md
deleted file mode 100644
index 6a25a413..00000000
--- a/docs/md-documentation.md
+++ /dev/null
@@ -1,442 +0,0 @@
----
-lastproofread: '2021-06-25'
----
-
-(documentation)=
-
-# Write Documentation
-
-We encourage every VyOS user to help us improve our documentation as we have
-a deficit like most software projects. This not only helps you when reading
-but also everyone else.
-
-:::{warning}
-Please read and sign the
-{doc}`Contributor License Agreement<contributing/cla>` before submitting any
-documentation updates.
-:::
-
-If you are willing to contribute to our documentation this is the definite
-guide how to do so.
-
-:::{note}
-In contrast to submitting code patches, there is no requirement that
-you open up a [Phabricator](https://vyos.dev/) task prior to submitting a Pull-Request to the
-documentation.
-:::
-
-VyOS documentation is written in reStructuredText and generated to Read the Docs
-pages with Sphinx, as per the Python tradition. We welcome all sorts of
-contributions to the documentation.
-Not just new additions but also corrections to existing documentation.
-
-The documentation source is kept in the Git repository at
-<https://github.com/vyos/vyos-documentation> and you can follow the instructions
-in the [README.md] to build and test your changes.
-
-You can either install Sphinx and build the documentation locally,
-or use the [Dockerfile] to build it in a container.
-
-## Guidelines
-
-There are a few things to keep in mind when contributing to the
-documentation, for the sake of consistency and readability.
-
-The following is a quick summary of the rules:
-
-- Use American English at all times. It's always a good idea to run
-  your text through a grammar and spell checker, such as [Grammarly].
-- Don't forget to update `index.rst` when adding a new node.
-- Try not to exceed 80 characters per line, but don't break URLs over this.
-- Properly quote commands, filenames and brief code snippets with double backticks.
-- Use literal blocks for longer snippets.
-- Leave a newline before and after a header.
-- Indent with two spaces.
-- When in doubt, follow the style of existing documentation.
-
-And finally, remember that the reStructuredText files aren't
-exclusively for generating HTML and PDF. They should be human-readable
-and easily perused from a console.
-
-## Page content
-
-All RST files must follow the same TOC Level syntax and have to start with
-
-```{eval-rst}
-.. code-block::
-
-   #####
-   Title
-   #####
-```
-
-The configuration mode folder and the articles cover the specific level of
-the commands. The exact level depends on the command. This should provide
-stability for URLs used in the forum or blogpost.
-
-For example:
-
-> - `set firewall zone` is written in `firewall/zone.rst`
-> - `set interfaces ethernet` is written in `interfaces/ethernet.rst`
-
-In the configuration part of the page, all possible configuration options
-should be documented. Use `.. cfgcmd::` described above.
-
-Related operation command must be documented in the next part of the article.
-Use `::opcmd..` for these commands.
-
-Each page must contain the following parts:
-
-### 1. Theoretical information
-
-Theoretical information required for users to understand the next document sections:
-
-> - a simple explanation of what is this page about, why or when it is required to be used
-> - references to standards, RFCs
-
-### 2. Configuration description
-
-> Describe CLI items related to the service or use case. Each config line
-> or section must be explained, using information provided in the 1st part
-> of the page.
-
-### 3. Configuration examples
-
-> Practical examples of the service or use case configuration. They must
-> contain topology maps (if applicable) and short descriptions.
-
-### 4. Known issues
-
-This section must contain a list of:
-
-> - known issues or potential problems for the service or use case
-> - workarounds for known issues (if any exist)
-
-### 5. Debugging
-
-Described procedures for debugging a service:
-
-> - how to collect logs or other debugging information (like `show` commands output)
-> - how to read and what to search for in logs and collected information
-> - what are indicators of good and bad states in debugging outputs
-
-## Style Guide
-
-### Formatting and Sphinxmarkup
-
-#### TOC Level
-
-We use the following syntax for Headlines.
-
-```none
-#####
-Title
-#####
-
-********
-Chapters
-********
-
-Sections
-========
-
-Subsections
------------
-
-Subsubsections
-^^^^^^^^^^^^^^
-
-Paragraphs
-""""""""""
-```
-
-
-#### Cross-References
-
-A plugin will be used to generate a reference label for each headline.
-To reference a page or a section in the documentation use the
-`{ref}` command.
-
-For example, you want to reference the headline **VLAN** in the
-**ethernet.rst** page. The plugin generates the label based on
-the headline and the file path.
-
-`` {ref}`configuration/interfaces/ethernet:vlan ``
-
-to use an alternative hyperlink use it this way:
-
-`` {ref}`Check out VLAN<configuration/interfaces/ethernet:vlan> ``
-
-##### handle build errors
-
-The plugin will warn on build if a headline has a duplicate name in the
-same document. To prevent this warning, you have to put a custom link on
-top of the headline.
-
-```none
-Section A
-==========
-
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr
-
-Example
--------
-
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr
-
-Section B
-==========
-
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr
-
-.. _section B example:
-
-Example
--------
-
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr
-```
-
-
-#### Address space
-
-Note the following RFCs ({rfc}`5737`, {rfc}`3849`, {rfc}`5389` and
-{rfc}`7042`), which describe the reserved public IP addresses and autonomous
-system numbers for the documentation:
-
-> - `192.0.2.0/24`
-> - `198.51.100.0/24`
-> - `203.0.113.0/24`
-> - `2001:db8::/32`
-> - 16bit ASN: `64496 - 64511`
-> - 32bit ASN: `65536 - 65551`
-> - Unicast MAC Addresses: `00-53-00` to `00-53-FF`
-> - Multicast MAC-Addresses: `90-10-00` to `90-10-FF`
-
-Please do not use other public address space.
-
-#### Line length
-
-Limit all lines to a maximum of 80 characters.
-
-Except in `.. code-block::` because it uses the html tag `<pre>` and
-renders the same line format from the source rst file.
-
-#### Autolinter
-
-Each GitHub pull request is automatically linted to check the address space and
-line length.
-
-Sometimes it is necessary to provide real IP addresses like in the
-{ref}`examples`. For this, please use the sphinx comment syntax
-`.. stop_vyoslinter` to stop the linter and `.. start_vyoslinter` to start.
-
-#### Custom Sphinx-doc Markup
-
-Custom commands have been developed for writing the documentation. Please
-make yourself comfortable with those commands as this eases the way we
-render the documentation.
-
-##### cfgcmd
-
-When documenting CLI commands, use the ``.. cfgcmd::`` directive
-for all configuration mode commands. An explanation of the described command
-should be added below this statement.
-Replace all variable contents with \<value> or something similar.
-
-With those custom commands, it will be possible to render them in a more
-descriptive way in the resulting HTML/PDF manual.
-
-```none
-.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress>
-
-   This will configure a static ARP entry, always resolving `192.0.2.100` to
-   `00:53:27:de:23:aa`.
-```
-
-For an inline configuration level command, use ``:cfgcmd:``
-
-```none
-:cfgcmd:`set interface ethernet eth0`
-```
-
-
-To extract a defaultvalue from the XML definitions add a ``:defaultvalue:``
-to ``.. cfgcmd::`` directive.
-To have this feature locally, the vyos-1x submodule must be initialized before.
-Please be aware to not update the submodule in your PR.
-
-```none
-.. cfgcmd:: set system conntrack table-size <1-50000000>
-    :defaultvalue:
-
-    The connection tracking table contains one entry for each connection being
-    tracked by the system.
-```
-
-
-##### opcmd
-
-When documenting operational level commands, use the ``.. opcmd::`` directive.
-An explanation of the described command should be added below this statement.
-
-With those custom commands, it is possible to render them in a more
-descriptive way in the resulting HTML/PDF manual.
-
-```none
-.. opcmd:: show protocols static arp
-
-   Display all known ARP table entries spanning across all interfaces
-```
-
-For an inline operational level command, use ``:opcmd:``
-
-```none
-:opcmd:`add system image`
-```
-
-##### cmdinclude
-
-To minimize redundancy, there is a special include directive. It includes a txt
-file and replace the `{{ var0 }}` - `{{ var9 }}` with the correct value.
-
-```none
-.. cmdinclude:: /_include/interface-address.txt
-   :var0: ethernet
-   :var1: eth1
-```
-
-the content of interface-address.txt looks like this
-
-```none
-.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp |
-   dhcpv6>
-
-   Configure interface `<interface>` with one or more interface
-   addresses.
-
-   * **address** can be specified multiple times as IPv4 and/or IPv6
-   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
-   * **dhcp** interface address is received by DHCP from a DHCP server
-   on this segment.
-   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
-   server on this segment.
-
-   Example:
-
-   .. code-block:: none
-
-      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24
-      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24
-      set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64
-      set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64
-```
-##### vytask
-
-When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup
-command called `vytask` that automatically renders to a proper Phabricator
-URL. This is heavily used in the {ref}`release-notes` section.
-
-```none
-* {vytask}`T1605` Fixed regression in L2TP/IPsec server
-* {vytask}`T1613` Netflow/sFlow captures IPv6 traffic correctly
-```
-
-## Forking Workflow
-
-The Forking Workflow is fundamentally different from other popular Git
-workflows. Instead of using a single server-side repository to act as the
-"central" codebase, it gives every developer their own server-side repository.
-This means that each contributor has not one, but two Git repositories: a
-private local one and a public server-side one.
-
-The main advantage of the Forking Workflow is that contributions can be
-integrated without the need for everybody to push to a single central
-repository. Developers push to their own server-side repositories, and only the
-project maintainer can push to the official repository. This allows the
-maintainer to accept commits from any developer without giving them write
-access to the official codebase.
-
-:::{note}
-Updates to our documentation should be delivered by a GitHub
-pull-request. This requires you already have a GitHub account.
-:::
-
-
-- Fork this project on GitHub <https://github.com/vyos/vyos-documentation/fork>
-
-- Clone fork to local machine, then change to that directory
-  `$ cd vyos-documentation`
-
-- Install the requirements `$ pip install -r requirements.txt`
-  (or something similar)
-
-- Create a new branch for your work, use a descriptive name of your work:
-  `$ git checkout -b <branch-name>`
-
-- Make all your changes - please keep our commit rules in mind
-  ({ref}`prepare_commit`). This mainly applies to proper commit messages
-  describing your change (how and why). Please check out the documentation of
-  [Sphinx-doc] or [reStructuredText] if you are not familiar with it. This is used
-  for writing our docs. Additional directives how to write in RST can be
-  obtained from [reStructuredTextDirectives].
-
-- Check your changes by locally building the documentation `$ make livehtml`.
-  Sphinx will build the html files in the `docs/_build` folder. We provide
-  you with a Docker container for an easy-to-use user experience. Check the
-  [README.md] file of this repository.
-
-- View modified files by calling `$ git status`. You will get an overview of
-  all files modified by you. You can add individual files to the Git Index in
-  the next step.
-
-- Add modified files to Git index `$ git add path/to/filename` or add all
-  unstaged files `$ git add .`. All files added to the Git index will be part
-  of you following Git commit.
-
-- Commit your changes with the message, `$ git commit -m "<commit message>"`
-  or use `$ git commit -v` to have your configured editor launched. You can
-  type in a commit message. Again please make yourself comfortable without
-  rules ({ref}`prepare_commit`).
-
-- Push commits to your GitHub project: `$ git push -u origin <branch-name>`
-
-- Submit pull-request. In GitHub visit the main repository and you should
-  see a banner suggesting to make a pull request. Fill out the form and
-  describe what you do.
-
-- Once pull requests have been approved, you may want to locally update
-  your forked repository too. First you'll have to add a second remote
-  called `upstream` which points to our main repository. `$ git remote add
-  upstream https://github.com/vyos/vyos-documentation.git`
-
-  Check your configured remote repositories:
-
-  ```none
-  $ git remote -v
-  origin    https://github.com/<username>/vyos-documentation.git (fetch)
-  origin    https://github.com/<username>/vyos.documentation.git (push)
-  upstream  https://github.com/vyos/vyos-documentation.git (fetch)
-  upstream  https://github.com/vyos/vyos-documentation.git (push)
-
-  ```
-
-  Your remote repo on Github is called `origin`, while the original repo you
-  have forked is called `upstream`. Now you can locally update your forked
-  repo.
-
-  ```none
-  $ git fetch upstream
-  $ git checkout current
-  $ git merge upstream/current
-```
-
-- If you also want to update your fork on GitHub, use the following: `$ git
-  push origin current`
-
-[dockerfile]: https://github.com/vyos/vyos-documentation/blob/current/docker/Dockerfile
-[grammarly]: https://www.grammarly.com/
-[readme.md]: https://github.com/vyos/vyos-documentation/blob/current/README.md
-[restructuredtext]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
-[restructuredtextdirectives]: https://docutils.sourceforge.io/docs/ref/rst/directives.html
-[sphinx-doc]: https://www.sphinx-doc.org