diff options
Diffstat (limited to 'docs/contributing/documentation.rst')
| -rw-r--r-- | docs/contributing/documentation.rst | 60 |
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 |