add new directives "cfcmd" and "opcmd"

1 files changed, 44 insertions, 16 deletions

diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index ba7407e4..b5ced664 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -14,8 +14,9 @@ guid how to do so.
    you open up a Phabricator_ task prior to submitting a Pull-Request to the
    documentation.
 
-Guide
------
+Git Workflow
+------------
+
 
 Updates to our documentation should be delivered by a GitHub pull-request. In
 order to create a pull-request you need to fork our documentation code first.
@@ -35,20 +36,6 @@ This requires you already have a GitHub account.
   describing your change. Please check the documentation if you aren't familiar
   with Sphinx-doc_ or reStructuredText_.
 
-  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.
 
 * Check your changes by locally building the documentation ``$ make html``
   Sphinx will build the html files in the ``docs/_build`` folder
@@ -92,6 +79,47 @@ This requires you already have a GitHub account.
   If you want to update your fork on GitHub, too use the following:
   ``$ git push origin master``
 
+
+Style Guide
+-----------
+
+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.
+
+
+Specific Sphinx-doc Markup
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When documenting CLI commands use the ``.. cfcmd::`` directive for
+the configuration mode and the ``.. opcmd::`` directive for operational mode
+commands.
+Under the command a short exlaination should be provide.
+
+Example:
+
+.. code-block::
+
+  .. opcmd:: show protocols static arp
+
+  Display all known ARP table entries spanning accross all interfaces
+
+
+
 .. _Sphinx-doc: https://www.sphinx-doc.org
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 .. _Phabricator: https://phabricator.vyos.net