vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

documentation guide - update grammar

Browse Source
This commit is contained in:
Ricky Pai 2021-04-05 05:56:31 -07:00 committed by GitHub
parent 6794f9ace7
commit 4a26755f13
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/documentation.rst
View File

@ -4,9 +4,9 @@
Documentation Documentation
############# #############
As most software projects we also have a lack in documentation. We encourage We encourage every VyOS user to help us improve our documentation as we have
every VyOS user to help us improve our documentation. This will not only be a deficit like most software projects. This not only be helps you when reading,
beneficial for you (when reading something up) but also for the whole world. but also everyone else.
If you are willing to contribute to our documentation this is the definite If you are willing to contribute to our documentation this is the definite
guide how to do so. guide how to do so.
@ -101,7 +101,7 @@ access to the official codebase.
$ git checkout master $ git checkout master
$ git merge upstream/master $ git merge upstream/master
* If you want to update your fork on GitHub, too use the following: ``$ git * If you also want to update your fork on GitHub, use the following: ``$ git
push origin master`` push origin master``
Style Guide Style Guide
@ -153,7 +153,7 @@ system numbers for the documentation:
* Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF`` * Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF``
* Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF`` * Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF``
Please don't use other public address space. Please do not use other public address space.
Line length Line length
@ -161,32 +161,32 @@ Line length
Limit all lines to a maximum of 80 characters. Limit all lines to a maximum of 80 characters.
Except in ``.. code-block::`` because it will use the html tag ``<pre>`` Except in ``.. code-block::`` because it uses the html tag ``<pre>`` and
which have the save line format as in the rst file. renders the same line format from the source rst file.
Autolinter Autolinter
^^^^^^^^^^ ^^^^^^^^^^
Each GitHub Pull request will automatically lint against the Address space and Each GitHub Pull request is automatically linted to check the Address space and
line length. line length.
Sometimes it is necessary to provide real IP Addresses like in the Sometimes it is necessary to provide real IP Addresses like in the
:ref:`examples`. For this please use the sphinx comment syntax :ref:`examples`. For this, please use the sphinx comment syntax
``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start. ``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start.
Custom Sphinx-doc Markup Custom Sphinx-doc Markup
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
When writing the documentation custom commands have been developed. Please Custom commands have been developed for writing the documentation. Please
make yourself comfortable with those commands as this eases the way we make yourself comfortable with those commands as this eases the way we
render the documentation. render the documentation.
cfgcmd cfgcmd
"""""" """"""
When documenting CLI commands use the ``.. cfgcmd::`` directive When documenting CLI commands, use the ``.. cfgcmd::`` directive
for all configuration mode commands. An explanation of the described command for all configuration mode commands. An explanation of the described command
should be added below this statement. should be added below this statement.
Replace all variable contents with <value> or somthing similar. Replace all variable contents with <value> or somthing similar.
@ -201,7 +201,7 @@ descriptive way in the resulting HTML/PDF manual.
This will configure a static ARP entry always resolving `192.0.2.100` to This will configure a static ARP entry always resolving `192.0.2.100` to
`00:53:27:de:23:aa`. `00:53:27:de:23:aa`.
For a inline configuration level command use ``:cfgcmd:`` For a inline configuration level command, use ``:cfgcmd:``
.. code-block:: none .. code-block:: none
@ -210,10 +210,10 @@ For a inline configuration level command use ``:cfgcmd:``
opcmd opcmd
""""" """""
When documenting operational level command use the ``.. opcmd::`` directive. When documenting operational level commands, use the ``.. opcmd::`` directive.
An explanation of the described command should be added below this statement. An explanation of the described command should be added below this statement.
With those custom commands it will be possible to render them in a more With those custom commands, it is possible to render them in a more
descriptive way in the resulting HTML/PDF manual. descriptive way in the resulting HTML/PDF manual.
.. code-block:: none .. code-block:: none
@ -222,7 +222,7 @@ descriptive way in the resulting HTML/PDF manual.
Display all known ARP table entries spanning across all interfaces Display all known ARP table entries spanning across all interfaces
For a inline operational level command use ``:opcmd:`` For a inline operational level command, use ``:opcmd:``
.. code-block:: none .. code-block:: none
@ -231,7 +231,7 @@ For a inline operational level command use ``:opcmd:``
cmdinclude cmdinclude
"""""""""" """"""""""
To minimize redundancy there is a special include directive. It include a txt To minimize redundancy, there is a special include directive. It include a txt
file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value
.. code-block:: none .. code-block:: none
@ -270,7 +270,7 @@ vytask
"""""" """"""
When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup
command called ``vytask`` which automatically renders to a proper Phabricator command called ``vytask`` that automatically renders to a proper Phabricator
URL. This is heavily used in the :ref:`release-notes` section. URL. This is heavily used in the :ref:`release-notes` section.
.. code-block:: none .. code-block:: none
@ -281,7 +281,7 @@ URL. This is heavily used in the :ref:`release-notes` section.
Page content Page content
------------ ------------
The documentation have 3 different types of pages, the same kind of pages must The documentation has 3 different types of pages. The same kind of pages must
have the same structure to achieve a recognition factor. have the same structure to achieve a recognition factor.
All RST files must follow the same TOC Level syntax and have to start with All RST files must follow the same TOC Level syntax and have to start with
@ -307,12 +307,12 @@ For example:
The article starts with a short intruducing about the command or the The article starts with a short intruducing about the command or the
technologie. Please include some helpfull links or background informations. technologie. Please include some helpfull links or background informations.
After this a optional section follows. Some commands have requirements like the An optional section follows. Some commands have requirements like compatible
compatible hardware (e.g. Wifi) or some commands you have to set before. For 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. example, it is recommended to set a route-map before configure BGP.
In the configuration part of the page all possible confiuration options In the configuration part of the page, all possible confiuration options
should be documented. Use ``.. cfgcmd::`` like described above. should be documented. Use ``.. cfgcmd::`` described above.
Related Operation command must be documented in the next part of the article. Related Operation command must be documented in the next part of the article.
Use ``::opcmd..`` for these commands. Use ``::opcmd..`` for these commands.
@ -323,16 +323,16 @@ next optional part.
Operation mode pages Operation mode pages
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
Operation mode commands, which didn't fit in a related configuraton mode command Operation mode commands that does not fit in a related configuraton mode command
must documented in this part of the documentation. must be documented in this part of the documentation.
General concepts for troubleshooting belong here as well as detailed process General concepts for troubleshooting, and detailed process descriptions belong
descriptions. here.
Anything else Anything else
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Anything else what is not a configuration or a operation command have no Anything else that is not a configuration or an operation command have no
predefined structure. predefined structure.