vyos-documentation/docs/contributing/documentation.rst

.. _documentation:

Documentation
-------------

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.

Guidelines
^^^^^^^^^^

There are a few small things to keep in mind when contributing to the
documentation, for the sake of consistency and readability. When in doubt,
follow the style of existing documentation.

Remember that the reStructuredText files aren't exclusively for generating
HTML and PDF. They should be human-readable and easily perused from a console.

- Use American English at all times. A spell checker can be helpful for this.
- 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 backticks.
- Use literal blocks for longer snippets.
- Leave a newline before and after a header.
- Indent with two spaces.

Building
^^^^^^^^

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.

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.

.. _Dockerfile: https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile