docs/CONTRIBUTING_DOCS.rst

   1 .. _contributing_docs:
   2
   3 Contributing documentation
   4 ==========================
   5
   6 |docs|
   7
   8 .. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
   9    :alt: Documentation Status
  10    :scale: 100%
  11    :target: https://TEMPLATE-formula.readthedocs.io/en/latest/?badge=latest
  12
  13 Toolchain
  14 ^^^^^^^^^
  15
  16 The documentation for this formula is written in
  17 `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
  18 (also known as RST, ReST, or reST).
  19 It is built by
  20 `Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
  21 and hosted on
  22 `Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
  23
  24 Adding a new page
  25 ^^^^^^^^^^^^^^^^^
  26
  27 Adding a new page involves two steps:
  28
  29 #. Use the
  30    :ref:`provided page template <saltstack_formulas_rst_page_template>`
  31    to create a new page.
  32 #. Add the page name under the ``toctree`` list in ``index.rst``.
  33
  34    a. Do not just append it to the list.
  35    #. Select the best place where it fits within the overall documentation.
  36
  37 SaltStack-Formulas' RST page template
  38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  39
  40 .. _saltstack_formulas_rst_page_template
  41
  42 Use the following template when creating a new page.
  43 This ensures consistency across the documentation for this formula.
  44 The heading symbols have been selected in accordance to the output rendered by the
  45 `Markdown to reStructuredText converter <https://github.com/miyakogi/m2r#restrictions>`_
  46 we are using for some of the pages of this documentation.
  47
  48 .. code-block:: rst
  49
  50    .. _template:
  51
  52    [Page title]
  53    ============
  54
  55    [Introductory paragraph]
  56
  57    .. contents:: **Table of Contents**
  58
  59    [Heading 2]
  60    -----------
  61
  62    [Heading 3]
  63    ^^^^^^^^^^^
  64
  65    [Heading 4]
  66    ~~~~~~~~~~~
  67
  68    [Heading 5]
  69    """""""""""
  70
  71    [Heading 6]
  72    ###########
  73
  74 #. The first line is an anchor that can be used to link back to (the top of)
  75    this file.
  76
  77    a. Change this to be the lowercase version of the file name.
  78    #. Do not include the ``.rst`` file extension.
  79    #. Use hyphens (``-``) instead of spaces or non-letter characters.
  80
  81 #. Change the ``[Page title]`` accordingly, matching the same number of equals
  82    signs (``=``) underneath.
  83 #. Change the ``[Introductory paragraph]`` to be a short summary of the page
  84    content.
  85    Use no more than three paragraphs for this.
  86 #. Leave the ``..contents:: **Table of Contents**`` line as it is.
  87 #. Use the remaining headings as required to break up the page content.
  88
  89    a. You will rarely need to use beyond ``[Heading 4]``.
  90    #. Again, no single heading should have more than about three paragraphs of
  91       content before the next heading or sub-heading is used.
  92
  93 Obviously, it is not necessary to follow the steps in the order above.
  94 For example, it is usually easier to write the ``[Introductory paragraph]``
  95 at the end.
  96