diff options
Diffstat (limited to 'docs/documentation.rst')
| -rw-r--r-- | docs/documentation.rst | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/docs/documentation.rst b/docs/documentation.rst new file mode 100644 index 00000000..40edf750 --- /dev/null +++ b/docs/documentation.rst @@ -0,0 +1,175 @@ +.. _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 +benefical four you (when reading something up) but also for the whole world. + +If you are willing to contribute to our documentation this is the definate +guid how to do so. + +.. note:: In contrast to submitting code patches there is no requirement that + you open up a Phabricator_ task prior to submitting a Pull-Request to the + 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 +"central" codebase, it gives every developer their own server-side repository. +This means that each contributor has not one, but two Git repositories: a +private local one and a public server-side one. + +The main advantage of the Forking Workflow is that contributions can be +integrated without the need for everybody to push to a single central +repository. Developers push to their own server-side repositories, and only the +project maintainer can push to the official repository. This allows the +maintainer to accept commits from any developer without giving them write +access to the official codebase. + +.. note:: Updates to our documentation should be delivered by a GitHub + pull-request. This requires you already have a GitHub account. + +* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork + +* Clone fork to local machine + +* Change to your new local directory ``$ cd vyos-documentation`` + +* Create new branch for your work, use a descriptive name of your work: + ``$ git checkout -b fix-vxlan-typo`` + +* Make all your changes - please keep our commit rules in mind + (: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. + +* Check your changes by locally building the documentation ``$ make html``. + Sphinx will build the html files in the ``docs/_build`` folder. We provide + you with a Docker container for an easy to use user experience. Check the + README.md_ file of this repository. + +* View modified files by calling ``$ git status``. You will get an overview of + all files modified by you. You can add individual files to the Git Index in + the next step. + +* Add modified files to Git index ``$ git add path/to/filename`` or add all + unstaged files ``$ git add .``. All files added to the Git index will be part + of you following Git commit. + +* Commit your changes ``$ git commit -v`` - your configured editor will now ne + launched where you can type in a commit message. Again please make yourself + comfortable with out rules (:ref:`prepare_commit`). + +* Push your commits to your GitHub project: ``$ git push -u origin foo-branch`` + +* Submit pull-request. In GitHub visit the main repository and you should + see a banner suggesting to make a pull request. Fill out the form and + describe what you do. + +* Once pull resquests have been approved, you may want to locally update + your forked repository too. First you'll have to add a second remote + called `upstream` which points to our main repository. ``$ git remote add + upstream https://github.com/vyos/vyos-documentation.git`` + + Check your configured remote repositories: + + .. code-block:: none + + $ git remote -v + origin https://github.com/<username>/vyos-documentation.git (fetch) + origin https://github.com/<username>/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + + Your remote repo on Github is called ``origin``, while the original repo you + have forked is called ``upstream``. Now you can locally update your forked + repo. + + .. code-block:: none + + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + +* If you want to update your fork on GitHub, too use the following: ``$ git + push origin master`` + +Style Guide +----------- + +Sections +^^^^^^^^ + +We use the following syntax for Headlines. + +.. code-block:: none + + ##### + Parts + ##### + + ******** + Chapters + ******** + + Sections + ======== + + Subsections + ----------- + + Subsubsections + ^^^^^^^^^^^^^^ + + Paragraphs + """""""""" + +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. + + +Custom Sphinx-doc Markup +^^^^^^^^^^^^^^^^^^^^^^^^ + +When documenting CLI commands use the ``.. cfgcmd::`` directive for all +configuration mode commands. When documenting operational level command use +the ``.. opcmd::`` directive. An explanation of the described command should +be added below this statement. + +**Example** + +.. code-block:: none + + .. opcmd:: show protocols static arp + + Display all known ARP table entries spanning accross all interfaces + + .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + + This will configure a static ARP entry always resolving `192.0.2.100` to + `00:53:27:de:23:aa`. + +.. _Sphinx-doc: https://www.sphinx-doc.org +.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _Phabricator: https://phabricator.vyos.net +.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md |