summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Göhler <github@ghlr.de>2019-11-23 14:00:52 +0100
committerChristian Poessinger <christian@poessinger.com>2019-11-23 14:00:52 +0100
commitf4c414ce4d899839adf28a8fba67c5ad7587e5ac (patch)
tree6c778066422f31c80d005f80ef49767049c843d0
parenta0a07c6ab314311909ee3c808d13a712cfba2fb2 (diff)
downloadvyos-documentation-f4c414ce4d899839adf28a8fba67c5ad7587e5ac.tar.gz
vyos-documentation-f4c414ce4d899839adf28a8fba67c5ad7587e5ac.zip
add new directives "cfcmd" and "opcmd"
-rw-r--r--docs/conf.py4
-rw-r--r--docs/contributing/documentation.rst60
-rw-r--r--docs/interfaces/wireless.rst14
-rw-r--r--docs/routing/arp.rst6
4 files changed, 58 insertions, 26 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 3fedc05c..1591b9bb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -167,3 +167,7 @@ texinfo_documents = [
author, 'VyOS', 'One line description of project.',
'Miscellaneous'),
]
+
+def setup(app):
+ app.add_object_type('opcmd', 'opcmd')
+ app.add_object_type('cfcmd', 'cfcmd')
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
diff --git a/docs/interfaces/wireless.rst b/docs/interfaces/wireless.rst
index e94eb09a..13eef0fe 100644
--- a/docs/interfaces/wireless.rst
+++ b/docs/interfaces/wireless.rst
@@ -25,7 +25,7 @@ its MAC address) and configured to run in monitor mode.
To be able to use the wireless interfaces you will first need to set a
regulatory domain with the country code of your locaion.
-.. option:: set system wifi-regulatory-domain DE
+.. cfcmd:: set system wifi-regulatory-domain DE
Configure system wide Wi-Fi regulatory domain. A reboot is required for this
change to be enabled.
@@ -188,7 +188,7 @@ Resulting in
Operational Commands
^^^^^^^^^^^^^^^^^^^^
-.. option:: show interfaces wireless info
+.. opcmd:: show interfaces wireless info
Use this command to view operational status and wireless-specific information
about all wireless interfaces.
@@ -199,7 +199,7 @@ about all wireless interfaces.
Interface Type SSID Channel
wlan0 access-point VyOS-TEST-0 1
-.. option:: show interfaces wireless detail
+.. opcmd:: show interfaces wireless detail
Use this command to view operational status and detailes wireless-specific
information about all wireless interfaces.
@@ -231,7 +231,7 @@ information about all wireless interfaces.
TX: bytes packets errors dropped carrier collisions
183413 5430 0 0 0 0
-.. option:: show interfaces wireless <wlanX>
+.. opcmd:: show interfaces wireless <wlanX>
This command shows both status and statistics on the specified wireless interface.
The wireless interface identifier can range from wlan0 to wlan999.
@@ -252,7 +252,7 @@ The wireless interface identifier can range from wlan0 to wlan999.
83413 430 0 0 0 0
-.. option:: show interfaces wireless <wlanX> brief
+.. opcmd:: show interfaces wireless <wlanX> brief
This command gives a brief status overview of a specified wireless interface.
The wireless interface identifier can range from wlan0 to wlan999.
@@ -266,7 +266,7 @@ The wireless interface identifier can range from wlan0 to wlan999.
wlan0 192.0.2.254/24 u/u
-.. option:: show interfaces wireless <wlanX> queue
+.. opcmd:: show interfaces wireless <wlanX> queue
Use this command to view wireless interface queue information.
The wireless interface identifier can range from wlan0 to wlan999.
@@ -279,7 +279,7 @@ The wireless interface identifier can range from wlan0 to wlan999.
rate 0bit 0pps backlog 0b 0p requeues 0
-.. option:: show interfaces wireless <wlanX> scan
+.. opcmd:: show interfaces wireless <wlanX> scan
This command is used to retrive information about WAP within the range of your
wireless interface. This command is usefull on wireless interfaces configured
diff --git a/docs/routing/arp.rst b/docs/routing/arp.rst
index 437a5bc3..11371d49 100644
--- a/docs/routing/arp.rst
+++ b/docs/routing/arp.rst
@@ -18,12 +18,12 @@ implemented.
Add static ARP entry
^^^^^^^^^^^^^^^^^^^^
-.. option:: set protocols static arp 10.1.1.100 hwaddr 08:00:27:de:23:aa
+.. cfcmd:: set protocols static arp 10.1.1.100 hwaddr 08:00:27:de:23:aa
Display ARP entries
^^^^^^^^^^^^^^^^^^^
-.. option:: show protocols static arp
+.. opcmd:: show protocols static arp
Display all known ARP table entries spanning accross all interfaces
@@ -35,7 +35,7 @@ Display all known ARP table entries spanning accross all interfaces
10.1.1.100 ether 08:00:27:de:23:aa CM eth1
-.. option:: show protocols static arp interface eth1
+.. opcmd:: show protocols static arp interface eth1
Display all known ARP table entries on a given interface only (`eth1`):