diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/documentation.rst | 46 |
1 files changed, 43 insertions, 3 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 2b2d3ba7..e8d1dba5 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -46,7 +46,8 @@ access to the official codebase. (:ref:`prepare_commit`). This mainly applies to proper commit messages describing your change (how and why). Please check out the documentation of Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used - for writing our docs. + for writing our docs. Additional directives how to write in RST can be obtained + from reStructuredTextDirectives_. * Check your changes by locally building the documentation ``$ make html``. Sphinx will build the html files in the ``docs/_build`` folder. We provide @@ -175,7 +176,7 @@ descriptive way in the resulting HTML/PDF manual. For a inline configuration level command use ``:cfgcmd:`` .. code-block:: none - + :cfgcmd:`set interface ethernet eth0` opcmd @@ -196,9 +197,47 @@ descriptive way in the resulting HTML/PDF manual. For a inline operational level command use ``:opcmd:`` .. code-block:: none - + :opcmd:`add system image` +cmdinclude +"""""""""" + +To minimize redundancy there is a special include directive. It include a txt +file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value + +.. code-block:: none + + .. cmdinclude:: interface-address.txt + :var0: ethernet + :var1: eth1 + +the content of interface-address.txt looks like this + +.. code-block:: none + + .. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 + vytask """""" @@ -214,6 +253,7 @@ URL. This is heavily used in the :ref:`release-notes` section. .. _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 |