diff options
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 60 | ||||
| -rw-r--r-- | docs/interfaces/wireless.rst | 14 | ||||
| -rw-r--r-- | docs/routing/arp.rst | 6 |
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`): |