Skip to content

Commit

Permalink
docs(rtd): clean up numerous issues and inconsistencies
Browse files Browse the repository at this point in the history 
* Include:
  - Fix link texts
  - Apply text formatting
  - Split some of the long lines (improved diffs)
  - Remove extra `\ ` appearing after conversion from Markdown
  - Improve ordered (numbered) nested lists
  - Use 3-character indents under RST directives
  - Use Jinja commenting in Jinja examples (not just `#`)
  • Loading branch information
@myii
myii committed Mar 3, 2019
1 parent 3f0071b commit ad5a8b8
Show file tree
Hide file tree
Showing 4 changed files with 190 additions and 188 deletions.
196 changes: 99 additions & 97 deletions docs/CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The key factor is that the first line of the commit message must follow this for

.. code-block::
type(scope): subject
type(scope): subject
* E.g. ``docs(contributing): add commit message formatting instructions``.
Expand All @@ -44,11 +44,11 @@ So based on the example above:

..
.. raw:: html
.. raw:: html

<h3>Documentation</h3>
<h3>Documentation</h3>

* **contributing:** add commit message formatting instructions
* **contributing:** add commit message formatting instructions


* The ``type`` translates into a ``Documentation`` sub-heading.
Expand All @@ -70,71 +70,73 @@ This formula applies some customisations to the defaults, as outlined in the tab
based upon the `type <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type>`_ of the commit:

.. list-table::
:name: commit-type-vs-version-bump
:header-rows: 1
:stub-columns: 0
:widths: 1,2,3,1,1

* - Type
- Heading
- Description
- Bump (default)
- Bump (custom)
* - ``build``
- Build System
- Changes related to the build system
- –
-
* - ``chore``
- –
- Changes to the build process or auxiliary tools and libraries such as documentation generation
- –
-
* - ``ci``
- Continuous Integration
- Changes to the continuous integration configuration
- –
-
* - ``docs``
- Documentation
- Documentation only changes
- –
- 0.0.1
* - ``feat``
- Features
- A new feature
- 0.1.0
-
* - ``fix``
- Bug Fixes
- A bug fix
- 0.0.1
-
* - ``perf``
- Performance Improvements
- A code change that improves performance
- 0.0.1
-
* - ``refactor``
- Code Refactoring
- A code change that neither fixes a bug nor adds a feature
- –
- 0.0.1
* - ``revert``
- Reverts
- A commit used to revert a previous commit
- –
- 0.0.1
* - ``style``
- Styles
- Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
- –
- 0.0.1
* - ``test``
- Tests
- Adding missing or correcting existing tests
- –
- 0.0.1
:name: commit-type-vs-version-bump
:header-rows: 1
:stub-columns: 0
:widths: 1,2,3,1,1

* - Type
- Heading
- Description
- Bump (default)
- Bump (custom)
* - ``build``
- Build System
- Changes related to the build system
- –
-
* - ``chore``
- –
- Changes to the build process or auxiliary tools and libraries such as
documentation generation
- –
-
* - ``ci``
- Continuous Integration
- Changes to the continuous integration configuration
- –
-
* - ``docs``
- Documentation
- Documentation only changes
- –
- 0.0.1
* - ``feat``
- Features
- A new feature
- 0.1.0
-
* - ``fix``
- Bug Fixes
- A bug fix
- 0.0.1
-
* - ``perf``
- Performance Improvements
- A code change that improves performance
- 0.0.1
-
* - ``refactor``
- Code Refactoring
- A code change that neither fixes a bug nor adds a feature
- –
- 0.0.1
* - ``revert``
- Reverts
- A commit used to revert a previous commit
- –
- 0.0.1
* - ``style``
- Styles
- Changes that do not affect the meaning of the code (white-space,
formatting, missing semi-colons, etc.)
- –
- 0.0.1
* - ``test``
- Tests
- Adding missing or correcting existing tests
- –
- 0.0.1

Use ``BREAKING CHANGE`` to trigger a ``major`` version change
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -149,11 +151,11 @@ An example of that:

.. code-block:: git
...
...
BREAKING CHANGE: With the removal of all of the `.sls` files under
`template/package/`, this formula no longer supports the installation of
packages.
BREAKING CHANGE: With the removal of all of the `.sls` files under
`template package`, this formula no longer supports the installation of
packages.
Documentation
-------------
Expand All @@ -175,11 +177,11 @@ Adding a new page
Adding a new page involves two steps:

#. Use the
:ref:`saltstack_formulas_rst_page_template <provided page template>`
:ref:`provided page template <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.
a. Do not just append it to the list.
#. Select the best place where it fits within the overall documentation.

SaltStack-Formulas' RST page template
Expand All @@ -195,50 +197,50 @@ we are using for some of the pages of this documentation.

.. code-block:: rst
.. _template:
.. _template:
[Page title]
============
[Page title]
============
[Introductory paragraph(s)]
[Introductory paragraph]
.. contents:: **Table of Contents**
.. contents:: **Table of Contents**
[Heading 2]
-----------
[Heading 2]
-----------
[Heading 3]
^^^^^^^^^^^
[Heading 3]
^^^^^^^^^^^
[Heading 4]
~~~~~~~~~~~
[Heading 4]
~~~~~~~~~~~
[Heading 5]
"""""""""""
[Heading 5]
"""""""""""
[Heading 6]
###########
[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.
a. 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
#. 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]``.
a. 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.
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)]``
For example, it is usually easier to write the ``[Introductory paragraph]``
at the end.

34 changes: 17 additions & 17 deletions docs/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@ template-formula
|img_travis| |docs| |img_sr|

.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/template-formula.svg?branch=master
:alt: Travis CI Build Status
:scale: 100%
:target: https://travis-ci.com/saltstack-formulas/template-formula
:alt: Travis CI Build Status
:scale: 100%
:target: https://travis-ci.com/saltstack-formulas/template-formula
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
:alt: Documentation Status
:scale: 100%
:target: https://template-formula.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
:scale: 100%
:target: https://template-formula.readthedocs.io/en/latest/?badge=latest
.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
:alt: Semantic Release
:scale: 100%
:target: https://github.com/semantic-release/semantic-release
:alt: Semantic Release
:scale: 100%
:target: https://github.com/semantic-release/semantic-release

A SaltStack formula that is empty. It has dummy content to help with a quick
start on a new formula and it serves as a style guide.
Expand All @@ -42,18 +42,18 @@ Contributing to this repo

**Commit message formatting is significant!!**

Please see :ref:`contributing <CONTRIBUTING>` for more details.
Please see :ref:`How to contribute <CONTRIBUTING>` for more details.

Available states
----------------

.. contents::
:local:
:local:

``template``
^^^^^^^^^^^^

Meta-state (This is a state that includes other states)
*Meta-state (This is a state that includes other states)*.

This installs the template package,
manages the template configuration file and then
Expand All @@ -79,7 +79,7 @@ via include list.
``template.clean``
^^^^^^^^^^^^^^^^^^

Meta-state (This is a state that includes other states)
*Meta-state (This is a state that includes other states)*.

this state will undo everything performed in the ``template`` meta-state in reverse order, i.e.
stops the service,
Expand All @@ -94,12 +94,12 @@ This state will stop the template service and disable it at boot time.
``template.config.clean``
^^^^^^^^^^^^^^^^^^^^^^^^^

This state will remove the configuration of the template service and has a dependency on ``template.service.clean``
via include list.
This state will remove the configuration of the template service and has a
dependency on ``template.service.clean`` via include list.

``template.package.clean``
^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will remove the template package and has a depency on ``template.config.clean``
via include list.
This state will remove the template package and has a depency on
``template.config.clean`` via include list.

Loading

0 comments on commit ad5a8b8

Please sign in to comment.