From 8bd516a5ff97716b34d254adf6cf9ac0126eb0f1 Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Thu, 10 Dec 2020 13:35:30 +0100
Subject: rearrange development part

---
 docs/contributing/debugging.rst     | 151 ----------------
 docs/contributing/documentation.rst | 331 ------------------------------------
 docs/contributing/index.rst         |   2 -
 docs/debugging.rst                  | 151 ++++++++++++++++
 docs/documentation.rst              | 331 ++++++++++++++++++++++++++++++++++++
 docs/index.rst                      |   5 +-
 6 files changed, 485 insertions(+), 486 deletions(-)
 delete mode 100644 docs/contributing/debugging.rst
 delete mode 100644 docs/contributing/documentation.rst
 create mode 100644 docs/debugging.rst
 create mode 100644 docs/documentation.rst

(limited to 'docs')

diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst
deleted file mode 100644
index a4c73d15..00000000
--- a/docs/contributing/debugging.rst
+++ /dev/null
@@ -1,151 +0,0 @@
-.. _debugging:
-
-#########
-Debugging
-#########
-
-There are two flags available to aid in debugging configuration scripts.
-Since configuration loading issues will manifest during boot, the flags are
-passed as kernel boot parameters.
-
-System Startup
-==============
-
-The system startup can be debugged (like loading in the configuration
-file from ``/config/config.boot``. This can be achieve by extending the
-Kernel command-line in the bootloader.
-
-Kernel
-------
-
-* ``vyos-debug`` - Adding the parameter to the linux boot line will produce
-  timing results for the execution of scripts during commit. If one is seeing
-  an unexpected delay during manual or boot commit, this may be useful in
-  identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found
-  in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``.
-
-* ``vyos-config-debug`` - During development, coding errors can lead to a
-  commit failure on boot, possibly resulting in a failed initialization of the
-  CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug``
-  will ensure access to the system as user ``vyos``, and will log a Python
-  stack trace to the file ``/tmp/boot-config-trace``.
-  File ``boot-config-trace`` will generate only if config loaded with a failure status.
-
-Live System
-===========
-
-A number of flags can be set up to change the behaviour of VyOS at runtime.
-These flags can be toggled using either environment variables or creating
-files.
-
-For each feature, a file called ``vyos.feature.debug`` can be created to
-toggle the feature on. If a parameter is required it can be placed inside
-the file as its first line.
-
-The file can be placed in ``/tmp`` for one time debugging (as the file
-will be removed on reboot) or placed in '/config' to stay permanently.
-
-For example, ``/tmp/vyos.ifconfig.debug`` can be created to enable
-interface debugging.
-
-It is also possible to set up the debugging using environment variables.
-In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG.
-
-For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash,
-will have the same effect as ``touch /tmp/vyos.ifconfig.debug``.
-
-* ``ifconfig`` - Once set, all commands used, and their responses received
-  from the OS, will be presented on the screen for inspection.
-
-* ``command`` - Once set, all commands used, and their responses received
-  from the OS, will be presented on the screen for inspection.
-
-* ``developer`` - Should a command fail, instead of printing a message to the
-  user explaining how to report issues, the python interpreter will start a
-  PBD post-mortem session to allow the developer to debug the issue. As the
-  debugger will wait from input from the developer, it has the capacity to
-  prevent a router to boot and therefore should only be permanently set up
-  on production if you are ready to see the OS fail to boot.
-
-* ``log`` - In some rare cases, it may be useful to see what the OS is doing,
-  including during boot. This option sends all commands used by VyOS to a
-  file. The default file is ``/tmp/full-log`` but it can be changed.
-
-.. note:: In order to retrieve the debug output on the command-line you need to
-  disable ``vyos-configd`` in addition. This can be run either one-time by calling
-  ``sudo systemctl stop vyos-configd`` or make this reboot-safe by calling
-  ``sudo systemctl disable vyos-configd``.
-
-Config Migration Scripts
-------------------------
-
-When writing a new configuration migrator it may happen that you see an error
-when you try to invoke it manually on a development system. This error will
-look like:
-
-.. code-block:: none
-
-  vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot
-  Traceback (most recent call last):
-    File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module>
-      config = ConfigTree(config_file)
-    File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__
-      raise ValueError("Failed to parse config: {0}".format(msg))
-  ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax.
-
-The reason is that the configuration migration backend is rewritten and uses
-a new form of "magic string" which is applied on demand when real config
-migration is run on boot. When runnint individual migrators for testing,
-you need to convert the "magic string" on your own by:
-
-.. code-block:: none
-
-  vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot
-
-Configuration Error on System Boot
-----------------------------------
-
-Beeing brave and running the latest rolling releases will sometimes trigger
-bugs due to corner cases we missed in our design. Those bugs should be filed
-via Phabricator_ but you can help us to narrow doen the issue. Login to your
-VyOS system and change into configuration mode by typing ``configure``. Now
-re-load your boot configuration by simply typing ``load`` followed by return.
-
-You shoudl now see a Python backtrace which will help us to handle the issue,
-please attach it to the Phabricator_ task.
-
-Boot Timing
------------
-
-During the migration and extensive rewrite of functionality from Perl into
-Python a significant increase in the overall system boottime was noticed. The
-system boot time can be analysed and a graph can be generated in the end which
-shows in detail who called whom during the system startup phase.
-
-This is done by utilizing the ``systemd-bootchart`` package which is now
-installed by default on the VyOS 1.3 (equuleus) branch. The configuration is
-also versioned so we get comparable results. ``systemd-bootchart`` is configured
-using this file: bootchart.conf_
-
-To enable boot time graphing change the Kernel commandline and add the folowing
-string: ``init=/usr/lib/systemd/systemd-bootchart``
-
-This can also be done permanently by changing ``/boot/grub/grub.cfg``.
-
-Priorities
-==========
-
-VyOS CLI is all about priorities. Every CLI node has a corresponding ``node.def``
-file and possibly an attached script that is executed when the node is present.
-Nodes can have a priority, and on system bootup - or any other ``commit`` to the
-config all scripts are executed from lowest to higest priority. This is good as
-this gives a deterministic behavior.
-
-To debug issues in priorities or to see what's going on in the background you can
-use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you the execution
-order of the scripts.
-
-.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg
-.. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf
-
-.. include:: /_include/common-references.txt
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
deleted file mode 100644
index f1dc8095..00000000
--- a/docs/contributing/documentation.rst
+++ /dev/null
@@ -1,331 +0,0 @@
-.. _documentation:
-
-#############
-Documentation
-#############
-
-As most software projects we also have a lack in documentation. We encourage
-every VyOS user to help us improve our documentation. This will not only be
-beneficial for you (when reading something up) but also for the whole world.
-
-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_ task prior to submitting a Pull-Request to the
-   documentation.
-
-Forking Workflow
-================
-
-The Forking Workflow is fundamentally different than 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 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 html``.
-  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 with out
-  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 resquests 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:
-
-  .. code-block:: 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.
-
-  .. code-block:: none
-
-    $ git fetch upstream
-    $ git checkout master
-    $ git merge upstream/master
-
-* If you want to update your fork on GitHub, too use the following: ``$ git
-  push origin master``
-
-Style Guide
-===========
-
-Formating and Sphinxmarkup
---------------------------
-
-TOC Level
-^^^^^^^^^^
-
-We use the following syntax for Headlines.
-
-.. code-block:: none
-
-  #####
-  Title
-  #####
-
-  ********
-  Chapters
-  ********
-
-  Sections
-  ========
-
-  Subsections
-  -----------
-
-  Subsubsections
-  ^^^^^^^^^^^^^^
-
-  Paragraphs
-  """"""""""
-
-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 don't use other public address space.
-
-
-Line length
-^^^^^^^^^^^
-
-Limit all lines to a maximum of 79 characters.
-
-Except in ``.. code-block::`` because it will use  the html tag ``<pre>``
-which have the save line format as in the rst file.
-
-
-Custom Sphinx-doc Markup
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-When writing the documentation custom commands have been developed. 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 somthing similar.
-
-With those custom commands it will be possible to render them in a more
-descriptive way in the resulting HTML/PDF manual.
-
-.. code-block:: 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 a inline configuration level command use ``:cfgcmd:``
-
-.. code-block:: none
-
-  :cfgcmd:`set interface ethernet eth0`
-
-opcmd
-"""""
-
-When documenting operational level command use the ``.. opcmd::`` directive.
-An explanation of the described command should be added below this statement.
-
-With those custom commands it will be possible to render them in a more
-descriptive way in the resulting HTML/PDF manual.
-
-.. code-block:: none
-
-  .. opcmd:: show protocols static arp
-
-     Display all known ARP table entries spanning across all interfaces
-
-For a inline operational level command use ``:opcmd:``
-
-.. code-block:: none
-
-  :opcmd:`add system image`
-
-cmdinclude
-""""""""""
-
-To minimize redundancy there is a special include directive. It include a txt
-file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value
-
-.. code-block:: none
-
-   .. cmdinclude:: /_include/interface-address.txt
-      :var0: ethernet
-      :var1: eth1
-
-the content of interface-address.txt looks like this
-
-.. code-block:: 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`` which automatically renders to a proper Phabricator
-URL. This is heavily used in the :ref:`release-notes` section.
-
-.. code-block:: none
-
-  * :vytask:`T1605` Fixed regression in L2TP/IPsec server
-  * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly
-
-Page content
-------------
-
-The documentation have 3 different types of pages, the same kind of pages must 
-have the same structure to achieve a recognition factor.
-
-All RST files must follow the same TOC Level syntax and have to start with
-
-.. code-block::
-
-   #####
-   Titel
-   #####
-
-Configuration mode pages
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-A configuration mode folder and article covers a specific level of a command.
-The exact level depends on the command. This should provide stability for URLs
-used in the forum or blogpost.
-
-For example:
-
-  * ``set zone-policy`` is written in ``zone-policy/index.rst``
-  * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst``
-
-The article starts with a short intruducing about the command or the technologie.
-Please include some helpfull links or background informations.
-
-After this a optional section follows. Some commands have requirements like the
-compatible hardware (e.g. Wifi) or some commands you have to set before. For
-example it is recommended to set a route-map before configure bgp.
-
-In the configuration part of the page all possible confiuration options
-should be documented. Use ``.. cfgcmd::`` like described above.
-
-Related Operation command must be documented in the next part of the article.
-Use ``::opcmd..`` for these commands.
-
-If there some troubleshooting guides releated to the commands. Explain it in the
-next optional part.
-
-Operation mode pages
-^^^^^^^^^^^^^^^^^^^^
-
-Operation mode commands, which didn't fit in a related configuraton mode command
-must documented in this part of the documentation.
-
-General concepts for troubleshooting belong here as well as detailed process
-descriptions.
-
-Anything else
-^^^^^^^^^^^^^
-
-Anything else what is not a configuration or a operation command have no
-predefined structure.
-
-
-.. _Sphinx-doc: https://www.sphinx-doc.org
-.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
-.. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html
-.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
-
-.. include:: /_include/common-references.txt
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index c3bb2688..2ecbcb5f 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -6,8 +6,6 @@ Contributing
    :maxdepth: 2
 
    build-vyos
-   debugging
    development
-   documentation
    issues-features
    upstream-packages
\ No newline at end of file
diff --git a/docs/debugging.rst b/docs/debugging.rst
new file mode 100644
index 00000000..a4c73d15
--- /dev/null
+++ b/docs/debugging.rst
@@ -0,0 +1,151 @@
+.. _debugging:
+
+#########
+Debugging
+#########
+
+There are two flags available to aid in debugging configuration scripts.
+Since configuration loading issues will manifest during boot, the flags are
+passed as kernel boot parameters.
+
+System Startup
+==============
+
+The system startup can be debugged (like loading in the configuration
+file from ``/config/config.boot``. This can be achieve by extending the
+Kernel command-line in the bootloader.
+
+Kernel
+------
+
+* ``vyos-debug`` - Adding the parameter to the linux boot line will produce
+  timing results for the execution of scripts during commit. If one is seeing
+  an unexpected delay during manual or boot commit, this may be useful in
+  identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found
+  in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``.
+
+* ``vyos-config-debug`` - During development, coding errors can lead to a
+  commit failure on boot, possibly resulting in a failed initialization of the
+  CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug``
+  will ensure access to the system as user ``vyos``, and will log a Python
+  stack trace to the file ``/tmp/boot-config-trace``.
+  File ``boot-config-trace`` will generate only if config loaded with a failure status.
+
+Live System
+===========
+
+A number of flags can be set up to change the behaviour of VyOS at runtime.
+These flags can be toggled using either environment variables or creating
+files.
+
+For each feature, a file called ``vyos.feature.debug`` can be created to
+toggle the feature on. If a parameter is required it can be placed inside
+the file as its first line.
+
+The file can be placed in ``/tmp`` for one time debugging (as the file
+will be removed on reboot) or placed in '/config' to stay permanently.
+
+For example, ``/tmp/vyos.ifconfig.debug`` can be created to enable
+interface debugging.
+
+It is also possible to set up the debugging using environment variables.
+In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG.
+
+For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash,
+will have the same effect as ``touch /tmp/vyos.ifconfig.debug``.
+
+* ``ifconfig`` - Once set, all commands used, and their responses received
+  from the OS, will be presented on the screen for inspection.
+
+* ``command`` - Once set, all commands used, and their responses received
+  from the OS, will be presented on the screen for inspection.
+
+* ``developer`` - Should a command fail, instead of printing a message to the
+  user explaining how to report issues, the python interpreter will start a
+  PBD post-mortem session to allow the developer to debug the issue. As the
+  debugger will wait from input from the developer, it has the capacity to
+  prevent a router to boot and therefore should only be permanently set up
+  on production if you are ready to see the OS fail to boot.
+
+* ``log`` - In some rare cases, it may be useful to see what the OS is doing,
+  including during boot. This option sends all commands used by VyOS to a
+  file. The default file is ``/tmp/full-log`` but it can be changed.
+
+.. note:: In order to retrieve the debug output on the command-line you need to
+  disable ``vyos-configd`` in addition. This can be run either one-time by calling
+  ``sudo systemctl stop vyos-configd`` or make this reboot-safe by calling
+  ``sudo systemctl disable vyos-configd``.
+
+Config Migration Scripts
+------------------------
+
+When writing a new configuration migrator it may happen that you see an error
+when you try to invoke it manually on a development system. This error will
+look like:
+
+.. code-block:: none
+
+  vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot
+  Traceback (most recent call last):
+    File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module>
+      config = ConfigTree(config_file)
+    File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__
+      raise ValueError("Failed to parse config: {0}".format(msg))
+  ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax.
+
+The reason is that the configuration migration backend is rewritten and uses
+a new form of "magic string" which is applied on demand when real config
+migration is run on boot. When runnint individual migrators for testing,
+you need to convert the "magic string" on your own by:
+
+.. code-block:: none
+
+  vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot
+
+Configuration Error on System Boot
+----------------------------------
+
+Beeing brave and running the latest rolling releases will sometimes trigger
+bugs due to corner cases we missed in our design. Those bugs should be filed
+via Phabricator_ but you can help us to narrow doen the issue. Login to your
+VyOS system and change into configuration mode by typing ``configure``. Now
+re-load your boot configuration by simply typing ``load`` followed by return.
+
+You shoudl now see a Python backtrace which will help us to handle the issue,
+please attach it to the Phabricator_ task.
+
+Boot Timing
+-----------
+
+During the migration and extensive rewrite of functionality from Perl into
+Python a significant increase in the overall system boottime was noticed. The
+system boot time can be analysed and a graph can be generated in the end which
+shows in detail who called whom during the system startup phase.
+
+This is done by utilizing the ``systemd-bootchart`` package which is now
+installed by default on the VyOS 1.3 (equuleus) branch. The configuration is
+also versioned so we get comparable results. ``systemd-bootchart`` is configured
+using this file: bootchart.conf_
+
+To enable boot time graphing change the Kernel commandline and add the folowing
+string: ``init=/usr/lib/systemd/systemd-bootchart``
+
+This can also be done permanently by changing ``/boot/grub/grub.cfg``.
+
+Priorities
+==========
+
+VyOS CLI is all about priorities. Every CLI node has a corresponding ``node.def``
+file and possibly an attached script that is executed when the node is present.
+Nodes can have a priority, and on system bootup - or any other ``commit`` to the
+config all scripts are executed from lowest to higest priority. This is good as
+this gives a deterministic behavior.
+
+To debug issues in priorities or to see what's going on in the background you can
+use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you the execution
+order of the scripts.
+
+.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg
+.. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf
+
+.. include:: /_include/common-references.txt
diff --git a/docs/documentation.rst b/docs/documentation.rst
new file mode 100644
index 00000000..f1dc8095
--- /dev/null
+++ b/docs/documentation.rst
@@ -0,0 +1,331 @@
+.. _documentation:
+
+#############
+Documentation
+#############
+
+As most software projects we also have a lack in documentation. We encourage
+every VyOS user to help us improve our documentation. This will not only be
+beneficial for you (when reading something up) but also for the whole world.
+
+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_ task prior to submitting a Pull-Request to the
+   documentation.
+
+Forking Workflow
+================
+
+The Forking Workflow is fundamentally different than 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 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 html``.
+  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 with out
+  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 resquests 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:
+
+  .. code-block:: 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.
+
+  .. code-block:: none
+
+    $ git fetch upstream
+    $ git checkout master
+    $ git merge upstream/master
+
+* If you want to update your fork on GitHub, too use the following: ``$ git
+  push origin master``
+
+Style Guide
+===========
+
+Formating and Sphinxmarkup
+--------------------------
+
+TOC Level
+^^^^^^^^^^
+
+We use the following syntax for Headlines.
+
+.. code-block:: none
+
+  #####
+  Title
+  #####
+
+  ********
+  Chapters
+  ********
+
+  Sections
+  ========
+
+  Subsections
+  -----------
+
+  Subsubsections
+  ^^^^^^^^^^^^^^
+
+  Paragraphs
+  """"""""""
+
+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 don't use other public address space.
+
+
+Line length
+^^^^^^^^^^^
+
+Limit all lines to a maximum of 79 characters.
+
+Except in ``.. code-block::`` because it will use  the html tag ``<pre>``
+which have the save line format as in the rst file.
+
+
+Custom Sphinx-doc Markup
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When writing the documentation custom commands have been developed. 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 somthing similar.
+
+With those custom commands it will be possible to render them in a more
+descriptive way in the resulting HTML/PDF manual.
+
+.. code-block:: 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 a inline configuration level command use ``:cfgcmd:``
+
+.. code-block:: none
+
+  :cfgcmd:`set interface ethernet eth0`
+
+opcmd
+"""""
+
+When documenting operational level command use the ``.. opcmd::`` directive.
+An explanation of the described command should be added below this statement.
+
+With those custom commands it will be possible to render them in a more
+descriptive way in the resulting HTML/PDF manual.
+
+.. code-block:: none
+
+  .. opcmd:: show protocols static arp
+
+     Display all known ARP table entries spanning across all interfaces
+
+For a inline operational level command use ``:opcmd:``
+
+.. code-block:: none
+
+  :opcmd:`add system image`
+
+cmdinclude
+""""""""""
+
+To minimize redundancy there is a special include directive. It include a txt
+file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value
+
+.. code-block:: none
+
+   .. cmdinclude:: /_include/interface-address.txt
+      :var0: ethernet
+      :var1: eth1
+
+the content of interface-address.txt looks like this
+
+.. code-block:: 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`` which automatically renders to a proper Phabricator
+URL. This is heavily used in the :ref:`release-notes` section.
+
+.. code-block:: none
+
+  * :vytask:`T1605` Fixed regression in L2TP/IPsec server
+  * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly
+
+Page content
+------------
+
+The documentation have 3 different types of pages, the same kind of pages must 
+have the same structure to achieve a recognition factor.
+
+All RST files must follow the same TOC Level syntax and have to start with
+
+.. code-block::
+
+   #####
+   Titel
+   #####
+
+Configuration mode pages
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A configuration mode folder and article covers a specific level of a command.
+The exact level depends on the command. This should provide stability for URLs
+used in the forum or blogpost.
+
+For example:
+
+  * ``set zone-policy`` is written in ``zone-policy/index.rst``
+  * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst``
+
+The article starts with a short intruducing about the command or the technologie.
+Please include some helpfull links or background informations.
+
+After this a optional section follows. Some commands have requirements like the
+compatible hardware (e.g. Wifi) or some commands you have to set before. For
+example it is recommended to set a route-map before configure bgp.
+
+In the configuration part of the page all possible confiuration options
+should be documented. Use ``.. cfgcmd::`` like described above.
+
+Related Operation command must be documented in the next part of the article.
+Use ``::opcmd..`` for these commands.
+
+If there some troubleshooting guides releated to the commands. Explain it in the
+next optional part.
+
+Operation mode pages
+^^^^^^^^^^^^^^^^^^^^
+
+Operation mode commands, which didn't fit in a related configuraton mode command
+must documented in this part of the documentation.
+
+General concepts for troubleshooting belong here as well as detailed process
+descriptions.
+
+Anything else
+^^^^^^^^^^^^^
+
+Anything else what is not a configuration or a operation command have no
+predefined structure.
+
+
+.. _Sphinx-doc: https://www.sphinx-doc.org
+.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html
+.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
+
+.. include:: /_include/common-references.txt
diff --git a/docs/index.rst b/docs/index.rst
index d66d7680..574a2c49 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,9 +37,10 @@ VyOS User Guide
 .. toctree::
    :maxdepth: 2
    :includehidden:
-   :caption: Contributing
-
+   :caption: Development
 
    contributing/index
+   debugging
+   documentation
    coverage
    copyright
-- 
cgit v1.2.3