Merge branch 'sagitta' of https://github.com/rebortg/vyos-documentation

5 files changed, 89 insertions, 14 deletions

diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst
index 40633535..a4c73d15 100644
--- a/docs/contributing/debugging.rst
+++ b/docs/contributing/debugging.rst
@@ -148,4 +148,4 @@ 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:: ../common-references.rst
+.. include:: /_include/common-references.txt
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 86371845..73b8b22e 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -711,4 +711,4 @@ http://dev.packages.vyos.net/repositories/.
 .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i
 .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i
 
-.. include:: ../common-references.rst
+.. include:: /_include/common-references.txt
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index e8d1dba5..1766d6ca 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -1,7 +1,8 @@
 .. _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
@@ -15,7 +16,7 @@ guide how to do so.
    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
@@ -102,17 +103,20 @@ access to the official codebase.
   push origin master``
 
 Style Guide
------------
+===========
 
-Sections
-^^^^^^^^
+Formating and Sphinxmarkup
+--------------------------
+
+TOC Level
+^^^^^^^^^^
 
 We use the following syntax for Headlines.
 
 .. code-block:: none
 
   #####
-  Parts
+  Title
   #####
 
   ********
@@ -159,16 +163,17 @@ 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.
+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:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa
+  .. 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`.
@@ -250,10 +255,67 @@ URL. This is heavily used in the :ref:`release-notes` section.
   * :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:: ../common-references.rst
+.. include:: /_include/common-references.txt
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 00000000..c3bb2688
--- /dev/null
+++ b/docs/contributing/index.rst
@@ -0,0 +1,13 @@
+############
+Contributing
+############
+
+.. toctree::
+   :maxdepth: 2
+
+   build-vyos
+   debugging
+   development
+   documentation
+   issues-features
+   upstream-packages
\ No newline at end of file
diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst
index 60e49974..9b6602f9 100644
--- a/docs/contributing/issues-features.rst
+++ b/docs/contributing/issues-features.rst
@@ -77,4 +77,4 @@ the left side under the specific project.
 .. _Slack: https://slack.vyos.io
 .. _Forum: https://forum.vyos.io
 
-.. include:: ../common-references.rst
+.. include:: /_include/common-references.txt