From 5a35f4d30e5c16bd85e811176cffa86b721112b7 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 18:59:58 +0300 Subject: refactor(swap): rename imported .md files to md- prefix for swap mechanism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs//md-.md alongside the existing docs//.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-.md source file ready to swap in. 🤖 Generated by [robots](https://vyos.io) --- docs/md-documentation.md | 442 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 442 insertions(+) create mode 100644 docs/md-documentation.md (limited to 'docs/md-documentation.md') diff --git a/docs/md-documentation.md b/docs/md-documentation.md new file mode 100644 index 00000000..6a25a413 --- /dev/null +++ b/docs/md-documentation.md @@ -0,0 +1,442 @@ +--- +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` 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 + 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 `` + +##### 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 `
` 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 \ 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  hwaddr 
+
+   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 }}  address 

+
+   Configure 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 
+
+- 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 `
+
+- 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 ""`
+  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 `
+
+- 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//vyos-documentation.git (fetch)
+  origin    https://github.com//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
-- 
cgit v1.2.3