diff options
Diffstat (limited to 'docs/contributing/documentation.rst')
| -rw-r--r-- | docs/contributing/documentation.rst | 236 |
1 files changed, 34 insertions, 202 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 8102e9a9..eb8db3e1 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -1,218 +1,50 @@ -.. _documentation: +.. _contrib-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 -beneficial for you (when reading something up) but also for the whole world. +VyOS documentation is written in reStructuredText and generated to Read the Docs +pages with Sphinx, as per the Python tradition, as well as PDF files for offline +use through LaTeX. -If you are willing to contribute to our documentation this is the definite -guide how to do so. +We welcome all sorts of contributions to the documentation. Not just +new additions but also corrections to existing documentation. -.. 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. +Guidelines +^^^^^^^^^^ -Forking Workflow ----------------- +There are a few things to keep in mind when contributing to the +documentation, for the sake of consistency and readability. -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. +Take a look at the :doc:`/documentation` page for an intricate explanation +of the documentation process. -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. +The following is a quick summary of the rules: -.. note:: Updates to our documentation should be delivered by a GitHub - pull-request. This requires you already have a GitHub account. +- Use American English at all times. It's always a good idea to run + your text through a grammar and spell checker, such as `Grammarly`_. +- Don't forget to update ``index.rst`` when adding a new node. +- Try not to exceed 80 characters per line, but don't break URLs over this. +- Properly quote commands, filenames and brief code snippets with double backticks. +- Use literal blocks for longer snippets. +- Leave a newline before and after a header. +- Indent with two spaces. +- When in doubt, follow the style of existing documentation. -* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork +And finally, remember that the reStructuredText files aren't +exclusively for generating HTML and PDF. They should be human-readable +and easily perused from a console. -* 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 +Building ^^^^^^^^ -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 writing the documentation custom commands have been developed. Please -make yourself comfortable with those commands as this eases the way we -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. - -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 - - This will configure a static ARP entry always resolving `192.0.2.100` to - `00:53:27:de:23:aa`. - -For a inline configuration level command use ``:cfgcmd:`` - -.. code-block:: none - - :cfgcmd:`set interface ethernet eth0` - -opcmd -""""" - -When documenting operational level command use the ``.. opcmd::`` directive. -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 -descriptive way in the resulting HTML/PDF manual. - -.. code-block:: none - - .. opcmd:: show protocols static arp - - Display all known ARP table entries spanning across all interfaces - -For a inline operational level command use ``:opcmd:`` - -.. code-block:: none - - :opcmd:`add system image` - -vytask -"""""" - -When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup -command called ``vytask`` which automatically renders to a proper Phabricator -URL. This is heavily used in the :ref:`release-notes` section. - -.. code-block:: none - - * :vytask:`T1605` Fixed regression in L2TP/IPsec server - * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +The source is kept in the Git repository +https://github.com/vyos/vyos-documentation +You can follow the instructions in the README to build and test your changes. -.. _Sphinx-doc: https://www.sphinx-doc.org -.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md +You can either install Sphinx (and TeX Live for PDF output) and build the +documentation locally, or use the `Dockerfile`_ to build it in a container. -.. include:: ../common-references.rst +.. _Dockerfile: https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile +.. _Grammarly: https://www.grammarly.com/ |