2.7 KiB
2.7 KiB
Contributing documentation
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:
- Use the
provided page template <saltstack_formulas_rst_page_template>
to create a new page. - Add the page name under the
toctree
list inindex.rst
.- Do not just append it to the list.
- 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] ###########
- The first line is an anchor that can be used to link back to (the
top of) this file.
- Change this to be the lowercase version of the file name.
- Do not include the
.rst
file extension. - Use hyphens (
-
) instead of spaces or non-letter characters.
- Change the
[Page title]
accordingly, matching the same number of equals signs (=
) underneath. - Change the
[Introductory paragraph]
to be a short summary of the page content. Use no more than three paragraphs for this. - Leave the
..contents:: **Table of Contents**
line as it is. - Use the remaining headings as required to break up the page content.
- You will rarely need to use beyond
[Heading 4]
. - Again, no single heading should have more than about three paragraphs of content before the next heading or sub-heading is used.
- You will rarely need to use beyond
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.