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.

We welcome all sorts of contributions to the documentation. Not just new additions but also corrections to existing documentation.

Guidelines

There are a few things to keep in mind when contributing to the documentation, for the sake of consistency and readability.

Take a look at the Documentation page for an intricate explanation of the documentation process.

The following is a quick summary of the rules:

  • 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.

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.

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.