diff options
Diffstat (limited to 'docs/contributing/documentation.rst')
| -rw-r--r-- | docs/contributing/documentation.rst | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst new file mode 100644 index 00000000..71495f4e --- /dev/null +++ b/docs/contributing/documentation.rst @@ -0,0 +1,39 @@ +.. _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 |