From dff0ee8ef85923c5998fa9b707ed3828d1fdc52b Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Sat, 2 Mar 2019 03:50:23 +0000 Subject: [PATCH] docs(contributing): add documentation contribution guidelines --- docs/CONTRIBUTING.rst | 115 ++++++++++++++++++++++++++++++++++++++---- docs/README.rst | 2 - docs/TOFS_pattern.rst | 1 - 3 files changed, 106 insertions(+), 12 deletions(-) diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst index a264a1ab..41cc2dac 100644 --- a/docs/CONTRIBUTING.rst +++ b/docs/CONTRIBUTING.rst @@ -5,12 +5,24 @@ How to contribute This document will eventually outline all aspects of guidance to make your contributing experience a fruitful and enjoyable one. What it already contains is information about *commit message formatting* and how that directly affects the numerous automated processes that are used for this repo. +It also covers how to contribute to this *formula's documentation*. .. contents:: **Table of Contents** +Overview +-------- + +Submitting a pull request is more than just code! +To achieve a quality product, the *tests* and *documentation* need to be updated as well. +An excellent pull request will include these in the changes, wherever relevant. + Commit message formatting ------------------------- +Since every type of change requires making Git commits, +we will start by covering the importance of ensuring that all of your commit +messages are in the correct format. + Automation of multiple processes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -49,7 +61,7 @@ Linting commit messages in Travis CI This formula uses `commitlint `_ for checking commit messages during CI testing. This ensures that they are in accordance with the ``semantic-release`` settings. -For more details about the default settings, refer back to the ``commitlint`` `reference rules `_. +For more details about the default settings, refer back to the ``commitlint`` `reference rules `_. Relationship between commit type and version bump ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,17 +84,17 @@ based upon the `type .`` An example of that: @@ -145,3 +155,90 @@ An example of that: `template/package/`, this formula no longer supports the installation of packages. +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 + :ref:`saltstack_formulas_rst_page_template ` + to create a new page. +#. Add the page name under the ``toctree`` list in ``index.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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _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. + +.. code-block:: rst + + .. _template: + + [Page title] + ============ + + [Introductory paragraph(s)] + + .. 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 ``=`` + underneath. +#. Change the ``[Introductory paragraph(s)]`` 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. + +Obviously, it is not necessary to follow the steps in the order above. +For example, it is usually easier to write the ``[Introductory paragraph(s)]`` +at the end. + diff --git a/docs/README.rst b/docs/README.rst index ff5cedd7..04306b92 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -37,7 +37,6 @@ which contains the currently released version. This formula is versioned accordi See `Formula Versioning Section `_ for more details. - Contributing to this repo ------------------------- @@ -45,7 +44,6 @@ Contributing to this repo Please see :ref:`contributing ` for more details. - Available states ---------------- diff --git a/docs/TOFS_pattern.rst b/docs/TOFS_pattern.rst index 61acca68..48642bdc 100644 --- a/docs/TOFS_pattern.rst +++ b/docs/TOFS_pattern.rst @@ -26,7 +26,6 @@ TOFS: A pattern for using SaltStack - https://github.com/myii - 23/02/2019 - All that follows is a proposal based on my experience with `SaltStack `_. The good thing of a piece of software like this is that you can "bend it" to suit your needs in many possible ways, and this is one of them. All the recommendations and thoughts are given "as it is" with no warranty of any type. .. contents:: **Table of Contents**