diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/documentation.rst | 89 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 13 |
2 files changed, 92 insertions, 10 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index e8d1dba5..9dd0c495 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -1,7 +1,8 @@ .. _documentation: +############# Documentation -============= +############# As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be @@ -15,7 +16,7 @@ guide how to do so. documentation. Forking Workflow ----------------- +================ The Forking Workflow is fundamentally different than other popular Git workflows. Instead of using a single server-side repository to act as the @@ -102,17 +103,20 @@ access to the official codebase. push origin master`` Style Guide ------------ +=========== -Sections -^^^^^^^^ +Formating and Sphinxmarkup +-------------------------- + +TOC Level +^^^^^^^^^^ We use the following syntax for Headlines. .. code-block:: none ##### - Parts + Title ##### ******** @@ -159,16 +163,17 @@ render the documentation. cfgcmd """""" -When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. An explanation of the described command should be -added below this statement. +When documenting CLI commands use the ``.. cfgcmd::`` directive +for all configuration mode commands. An explanation of the described command +should be added below this statement. +Replace all variable contents with <value> or somthing similar. With those custom commands it will be possible to render them in a more descriptive way in the resulting HTML/PDF manual. .. code-block:: none - .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + .. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress> This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. @@ -250,6 +255,70 @@ URL. This is heavily used in the :ref:`release-notes` section. * :vytask:`T1605` Fixed regression in L2TP/IPsec server * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +Page content +------------ + +The documentation have 3 different types of pages, the same kind of pages must +have the same structure to achieve a recognition factor. + +For all *.rst files must follow the same TOC Level syntax and have to start with + +.. code-block:: + + ##### + Titel + ##### + +Configuration mode pages +^^^^^^^^^^^^^^^^^^^^^^^^ + +A configuration mode article covers a specific level of a command. +The exact level depends on the command. + +For example: + + * ``set zone-policy`` is written in ``zone-policy/index.rst`` + * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst`` + +The article starts with a short intruducing about the command or the technologie. +Include some helpfull links or background informations. + +After this a optional section follows. Some commands have requirements like the +compatible hardware (e.g. Wifi) or some commands you have to set before. For +example it is recommended to set a route-map before configure bgp. + +In the configuration part of the page all possible confiuration options +should be documented. Use ``.. cfgcmd::`` like described above. + +Related Operation command must be documented in the next part of the articel. +Use ``::opcmd..`` for these commands. + +If there some troubleshooting guides releated to the commands. Explain it in the +next optional part. + +Examples: + + * ssh + + + +Operation mode pages +^^^^^^^^^^^^^^^^^^^^ + +Operation mode commands, which didn't fit in a related configuraton mode command +must documented in this part of the documentation. + +.. todo:: + + create structure + + +Anything else +^^^^^^^^^^^^^ + +Anything else what is not a configuration or a operation command have no +predefined structure. + .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..c3bb2688 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,13 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 2 + + build-vyos + debugging + development + documentation + issues-features + upstream-packages
\ No newline at end of file |