nsd-formula/docs/CONTRIBUTING_DOCS.rst
2021-04-01 23:00:17 +02:00

2.7 KiB

Contributing documentation

Documentation Status

Toolchain

The documentation for this formula is written in reStructuredText (also known as RST, ReST, or reST). It is built by Sphinx and hosted on Read the Docs.

Adding a new page

Adding a new page involves two steps:

  1. Use the provided page template <saltstack_formulas_rst_page_template> to create a new page.
  2. Add the page name under the toctree list in index.rst.
    1. Do not just append it to the list.
    2. Select the best place where it fits within the overall documentation.

SaltStack-Formulas' RST page template

Use the following template when creating a new page. This ensures consistency across the documentation for this formula. The heading symbols have been selected in accordance to the output rendered by the Markdown to reStructuredText converter we are using for some of the pages of this documentation.

.. _template:

[Page title]
============

[Introductory paragraph]

.. contents:: **Table of Contents**

[Heading 2]
-----------

[Heading 3]
^^^^^^^^^^^

[Heading 4]
~~~~~~~~~~~

[Heading 5]
"""""""""""

[Heading 6]
###########
  1. The first line is an anchor that can be used to link back to (the top of) this file.
    1. Change this to be the lowercase version of the file name.
    2. Do not include the .rst file extension.
    3. Use hyphens (-) instead of spaces or non-letter characters.
  2. Change the [Page title] accordingly, matching the same number of equals signs (=) underneath.
  3. Change the [Introductory paragraph] to be a short summary of the page content. Use no more than three paragraphs for this.
  4. Leave the ..contents:: **Table of Contents** line as it is.
  5. Use the remaining headings as required to break up the page content.
    1. You will rarely need to use beyond [Heading 4].
    2. Again, no single heading should have more than about three paragraphs of content before the next heading or sub-heading is used.

Obviously, it is not necessary to follow the steps in the order above. For example, it is usually easier to write the [Introductory paragraph] at the end.