diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/debugging.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 84 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 13 | ||||
| -rw-r--r-- | docs/contributing/issues-features.rst | 2 |
5 files changed, 89 insertions, 14 deletions
diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index 40633535..a4c73d15 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -148,4 +148,4 @@ order of the scripts. .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg .. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 86371845..73b8b22e 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -711,4 +711,4 @@ http://dev.packages.vyos.net/repositories/. .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index e8d1dba5..1766d6ca 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,10 +255,67 @@ 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. + +All RST files must follow the same TOC Level syntax and have to start with + +.. code-block:: + + ##### + Titel + ##### + +Configuration mode pages +^^^^^^^^^^^^^^^^^^^^^^^^ + +A configuration mode folder and article covers a specific level of a command. +The exact level depends on the command. This should provide stability for URLs +used in the forum or blogpost. + +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. +Please 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 article. +Use ``::opcmd..`` for these commands. + +If there some troubleshooting guides releated to the commands. Explain it in the +next optional part. + +Operation mode pages +^^^^^^^^^^^^^^^^^^^^ + +Operation mode commands, which didn't fit in a related configuraton mode command +must documented in this part of the documentation. + +General concepts for troubleshooting belong here as well as detailed process +descriptions. + +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 .. _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 +.. include:: /_include/common-references.txt 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 diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 60e49974..9b6602f9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -77,4 +77,4 @@ the left side under the specific project. .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt |