diff options
| -rw-r--r-- | docs/contributing/documentation.rst | 39 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 3 |
2 files changed, 41 insertions, 1 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 diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 2ecbcb5f..481c6da8 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -7,5 +7,6 @@ Contributing build-vyos development + documentation issues-features - upstream-packages
\ No newline at end of file + upstream-packages |