From 981cf62960fdc0471b0226bf6fe113d9cc9986ed Mon Sep 17 00:00:00 2001 From: erkin Date: Sat, 23 Jan 2021 14:58:47 +0300 Subject: docs: Add contribution guidelines --- docs/contributing/documentation.rst | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/contributing/documentation.rst (limited to 'docs/contributing/documentation.rst') 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 -- cgit v1.2.3