fix(pr): adopt pr comments
This commit is contained in:
N
parent
9a4923ec2e
commit
e4b924a884
63
.travis.yml
63
.travis.yml
@ -54,31 +54,40 @@ jobs:
|
||||
- npm i -D @commitlint/config-conventional
|
||||
@commitlint/travis-cli
|
||||
- commitlint-travis
|
||||
# Interrogate
|
||||
# - pip install --user interrogate
|
||||
# - interrogate .
|
||||
|
||||
## Define the rest of the matrix based on Kitchen testing
|
||||
# Make sure the instances listed below match up with
|
||||
# the `platforms` defined in `kitchen.yml`
|
||||
# NOTE: Please try to select up to six instances that add some meaningful
|
||||
# testing of the formula's behaviour. If possible, try to refrain from
|
||||
# the classical "chosing all the instances because I want to test on
|
||||
# another/all distro/s" trap: it will just add time to the testing (see
|
||||
# the discussion on #121). As an example, the set chosen below covers
|
||||
# the most used distros families, systemd and non-systemd and the latest
|
||||
# three supported Saltstack versions with python2 and 3.
|
||||
# As for `kitchen.yml`, that should still contain all of the platforms,
|
||||
# to allow for comprehensive local testing
|
||||
# Ref: https://github.com/saltstack-formulas/template-formula/issues/118
|
||||
# Ref: https://github.com/saltstack-formulas/template-formula/issues/121
|
||||
- env: INSTANCE=default-debian-10-master-py3
|
||||
- env: INSTANCE=default-ubuntu-1804-master-py3
|
||||
# env: INSTANCE=repo-ubuntu-1804-master-py3
|
||||
- env: INSTANCE=repo-centos-8-master-py3
|
||||
- env: INSTANCE=default-fedora-31-master-py3
|
||||
# - env: INSTANCE=default-opensuse-leap-151-master-py3
|
||||
- env: INSTANCE=default-amazonlinux-2-master-py3
|
||||
# - env: INSTANCE=default-debian-10-3000-2-py3
|
||||
# - env: INSTANCE=default-debian-9-3000-2-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-3000-2-py3
|
||||
# - env: INSTANCE=default-centos-8-3000-2-py3
|
||||
# - env: INSTANCE=default-centos-7-3000-2-py3
|
||||
# - env: INSTANCE=default-fedora-31-3000-2-py3
|
||||
# - env: INSTANCE=default-opensuse-leap-151-3000-2-py3
|
||||
# - env: INSTANCE=default-amazonlinux-2-3000-2-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-3000-2-py2
|
||||
# - env: INSTANCE=default-ubuntu-1604-3000-2-py2
|
||||
# - env: INSTANCE=arch-arch-base-latest-3000-2-py2
|
||||
# env: INSTANCE=default-ubuntu-2004-master-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-master-py3
|
||||
- env: INSTANCE=default-centos-8-master-py3
|
||||
# env: INSTANCE=default-fedora-32-master-py3
|
||||
# - env: INSTANCE=default-fedora-31-master-py3
|
||||
# - env: INSTANCE=default-opensuse-leap-152-master-py3
|
||||
# - env: INSTANCE=default-amazonlinux-2-master-py3
|
||||
# - env: INSTANCE=default-debian-10-3000-3-py3
|
||||
# - env: INSTANCE=default-debian-9-3000-3-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-3000-3-py3
|
||||
# - env: INSTANCE=default-centos-8-3000-3-py3
|
||||
# - env: INSTANCE=default-centos-7-3000-3-py3
|
||||
# - env: INSTANCE=default-fedora-31-3000-3-py3
|
||||
# env: INSTANCE=default-opensuse-leap-152-3000-3-py3
|
||||
# env: INSTANCE=default-amazonlinux-2-3000-3-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-3000-3-py2
|
||||
# - env: INSTANCE=default-ubuntu-1604-3000-3-py2
|
||||
# - env: INSTANCE=default-arch-base-latest-3000-3-py2
|
||||
# - env: INSTANCE=default-debian-10-2019-2-py3
|
||||
# - env: INSTANCE=default-debian-9-2019-2-py3
|
||||
# - env: INSTANCE=default-ubuntu-1804-2019-2-py3
|
||||
@ -86,7 +95,7 @@ jobs:
|
||||
# - env: INSTANCE=default-centos-8-2019-2-py3
|
||||
# - env: INSTANCE=default-centos-7-2019-2-py3
|
||||
# - env: INSTANCE=default-fedora-31-2019-2-py3
|
||||
# - env: INSTANCE=default-opensuse-leap-151-2019-2-py3
|
||||
# - env: INSTANCE=default-opensuse-leap-152-2019-2-py3
|
||||
# - env: INSTANCE=default-amazonlinux-2-2019-2-py3
|
||||
# - env: INSTANCE=default-centos-6-2019-2-py2
|
||||
# - env: INSTANCE=default-amazonlinux-1-2019-2-py2
|
||||
@ -117,15 +126,3 @@ jobs:
|
||||
edge: true
|
||||
# Run `semantic-release`
|
||||
script: 'npx semantic-release@15.14'
|
||||
|
||||
# Notification options: `always`, `never` or `change`
|
||||
notifications:
|
||||
webhooks:
|
||||
if: 'repo = saltstack-formulas/prometheus-formula'
|
||||
urls:
|
||||
- https://saltstack-formulas.zulipchat.com/api/v1/external/travis?api_key=HsIq3o5QmLxdnVCKF9is0FUIpkpAY79P&stream=CI&topic=saltstack-formulas%2Fprometheus-formula&ignore_pull_requests=true
|
||||
on_success: always # default: always
|
||||
on_failure: always # default: always
|
||||
on_start: always # default: never
|
||||
on_cancel: always # default: always
|
||||
on_error: always # default: always
|
||||
|
||||
10
AUTHORS.md
10
AUTHORS.md
@ -1,10 +0,0 @@
|
||||
# Authors
|
||||
|
||||
This list is sorted by the number of commits per contributor in _descending_ order.
|
||||
|
||||
Avatar|Contributor|Contributions
|
||||
:-:|---|:-:
|
||||
<img class='float-left rounded-1' src='https://avatars1.githubusercontent.com/u/13322818?v=4' width='36' height='36' alt='@noelmcloughlin'>|[@noelmcloughlin](https://github.com/noelmcloughlin)|1
|
||||
|
||||
---
|
||||
|
||||
@ -2,8 +2,7 @@
|
||||
|
||||
# SECTION: Owner(s) for everything in the repo, unless a later match takes precedence
|
||||
# FILE PATTERN OWNER(S)
|
||||
* @alxwr
|
||||
* @noelmcloughlin
|
||||
* @alxwr @noelmcloughlin
|
||||
|
||||
# SECTION: Owner(s) for specific directories
|
||||
# FILE PATTERN OWNER(S)
|
||||
|
||||
2
FORMULA
2
FORMULA
@ -1,7 +1,7 @@
|
||||
name: prometheus
|
||||
os: Debian, Ubuntu, Raspbian, RedHat, Fedora, CentOS, Amazon, Suse, openSUSE, Gentoo, Funtoo, Arch, Manjaro, Alpine, FreeBSD, OpenBSD, Solaris, SmartOS, Windows, MacOS
|
||||
os_family: Debian, RedHat, Suse, Gentoo, Arch, Alpine, FreeBSD, OpenBSD, Solaris, Windows, MacOS
|
||||
version: 0.2.2
|
||||
version: 3.3.0
|
||||
release: 1
|
||||
minimum_version: 2019.2
|
||||
summary: prometheus formula
|
||||
|
||||
@ -18,8 +18,11 @@ if File.file?(bundle_binstub)
|
||||
if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
|
||||
load(bundle_binstub)
|
||||
else
|
||||
abort('Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
|
||||
Replace `bin/bundle` by running `bundle binstubs bundler --force`, & run cmd again')
|
||||
abort(
|
||||
'Your `bin/bundle` was not generated by Bundler, '\
|
||||
'so this binstub cannot run. Replace `bin/bundle` by running '\
|
||||
'`bundle binstubs bundler --force`, then run this command again.'
|
||||
)
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
@ -1,86 +0,0 @@
|
||||
.. role:: raw-html-m2r(raw)
|
||||
:format: html
|
||||
|
||||
|
||||
Authors
|
||||
=======
|
||||
|
||||
This list is sorted by the number of commits per contributor in *descending* order.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Avatar
|
||||
- Contributor
|
||||
- Contributions
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/10231489?v=4' width='36' height='36' alt='@myii'>`
|
||||
- `@myii <https://github.com/myii>`_
|
||||
- 155
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/1800660?v=4' width='36' height='36' alt='@aboe76'>`
|
||||
- `@aboe76 <https://github.com/aboe76>`_
|
||||
- 22
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/242396?v=4' width='36' height='36' alt='@javierbertoli'>`
|
||||
- `@javierbertoli <https://github.com/javierbertoli>`_
|
||||
- 15
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars3.githubusercontent.com/u/3433835?v=4' width='36' height='36' alt='@n-rodriguez'>`
|
||||
- `@n-rodriguez <https://github.com/n-rodriguez>`_
|
||||
- 8
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/1396878?v=4' width='36' height='36' alt='@gravyboat'>`
|
||||
- `@gravyboat <https://github.com/gravyboat>`_
|
||||
- 6
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/1920805?v=4' width='36' height='36' alt='@alxwr'>`
|
||||
- `@alxwr <https://github.com/alxwr>`_
|
||||
- 5
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars3.githubusercontent.com/u/52996?v=4' width='36' height='36' alt='@daks'>`
|
||||
- `@daks <https://github.com/daks>`_
|
||||
- 5
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars3.githubusercontent.com/u/4542588?v=4' width='36' height='36' alt='@evvers'>`
|
||||
- `@evvers <https://github.com/evvers>`_
|
||||
- 4
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/3374962?v=4' width='36' height='36' alt='@nmadhok'>`
|
||||
- `@nmadhok <https://github.com/nmadhok>`_
|
||||
- 3
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/16338056?v=4' width='36' height='36' alt='@vutny'>`
|
||||
- `@vutny <https://github.com/vutny>`_
|
||||
- 2
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/29522418?v=4' width='36' height='36' alt='@k-hamza'>`
|
||||
- `@k-hamza <https://github.com/k-hamza>`_
|
||||
- 2
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars1.githubusercontent.com/u/528061?v=4' width='36' height='36' alt='@puneetk'>`
|
||||
- `@puneetk <https://github.com/puneetk>`_
|
||||
- 2
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars1.githubusercontent.com/u/3536289?v=4' width='36' height='36' alt='@andygabby'>`
|
||||
- `@andygabby <https://github.com/andygabby>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/1269218?v=4' width='36' height='36' alt='@Jokipii'>`
|
||||
- `@Jokipii <https://github.com/Jokipii>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars3.githubusercontent.com/u/5306980?v=4' width='36' height='36' alt='@johnkeates'>`
|
||||
- `@johnkeates <https://github.com/johnkeates>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/611471?v=4' width='36' height='36' alt='@duk3luk3'>`
|
||||
- `@duk3luk3 <https://github.com/duk3luk3>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars3.githubusercontent.com/u/3075069?v=4' width='36' height='36' alt='@marco-m'>`
|
||||
- `@marco-m <https://github.com/marco-m>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars1.githubusercontent.com/u/13322818?v=4' width='36' height='36' alt='@noelmcloughlin'>`
|
||||
- `@noelmcloughlin <https://github.com/noelmcloughlin>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars2.githubusercontent.com/u/91293?v=4' width='36' height='36' alt='@whiteinge'>`
|
||||
- `@whiteinge <https://github.com/whiteinge>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/22272?v=4' width='36' height='36' alt='@sroegner'>`
|
||||
- `@sroegner <https://github.com/sroegner>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars1.githubusercontent.com/u/117961?v=4' width='36' height='36' alt='@babilen5'>`
|
||||
- `@babilen5 <https://github.com/babilen5>`_
|
||||
- 1
|
||||
* - :raw-html-m2r:`<img class='float-left rounded-1' src='https://avatars0.githubusercontent.com/u/2205993?v=4' width='36' height='36' alt='@GMAzrael'>`
|
||||
- `@GMAzrael <https://github.com/GMAzrael>`_
|
||||
- 1
|
||||
|
||||
|
||||
----
|
||||
|
||||
Auto-generated by a `forked version <https://github.com/myii/maintainer>`_ of `gaocegege/maintainer <https://github.com/gaocegege/maintainer>`_ on 2019-05-31.
|
||||
@ -1,186 +0,0 @@
|
||||
.. _contributing:
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This formula uses `semantic-release <https://github.com/semantic-release/semantic-release>`_ for automating numerous processes such as bumping the version number appropriately, creating new tags/releases and updating the changelog.
|
||||
The entire process relies on the structure of commit messages to determine the version bump, which is then used for the rest of the automation.
|
||||
|
||||
Full details are available in the upstream docs regarding the `Angular Commit Message Conventions <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines>`_.
|
||||
The key factor is that the first line of the commit message must follow this format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
type(scope): subject
|
||||
|
||||
|
||||
* E.g. ``docs(contributing): add commit message formatting instructions``.
|
||||
|
||||
Besides the version bump, the changelog and release notes are formatted accordingly.
|
||||
So based on the example above:
|
||||
|
||||
..
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h3>Documentation</h3>
|
||||
|
||||
* **contributing:** add commit message formatting instructions
|
||||
|
||||
|
||||
* The ``type`` translates into a ``Documentation`` sub-heading.
|
||||
* The ``(scope):`` will be shown in bold text without the brackets.
|
||||
* The ``subject`` follows the ``scope`` as standard text.
|
||||
|
||||
Linting commit messages in Travis CI
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This formula uses `commitlint <https://github.com/conventional-changelog/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 <https://conventional-changelog.github.io/commitlint/#/reference-rules>`_.
|
||||
|
||||
Relationship between commit type and version bump
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This formula applies some customisations to the defaults, as outlined in the table below,
|
||||
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
|
||||
|
||||
Use ``BREAKING CHANGE`` to trigger a ``major`` version change
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Adding ``BREAKING CHANGE`` to the footer of the extended description of the commit message will **always** trigger a ``major`` version change, no matter which type has been used.
|
||||
This will be appended to the changelog and release notes as well.
|
||||
To preserve good formatting of these notes, the following format is prescribed:
|
||||
|
||||
* ``BREAKING CHANGE: <explanation in paragraph format>.``
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Semantic release formulas
|
||||
-------------------------
|
||||
|
||||
These formulas are already compatible with semantic-release:
|
||||
|
||||
* `bind-formula <https://github.com/saltstack-formulas/bind-formula>`_
|
||||
* `cert-formula <https://github.com/saltstack-formulas/cert-formula>`_
|
||||
* `chrony-formula <https://github.com/saltstack-formulas/chrony-formula>`_
|
||||
* `collectd-formula <https://github.com/saltstack-formulas/collectd-formula>`_
|
||||
* `fail2ban-formula <https://github.com/saltstack-formulas/fail2ban-formula>`_
|
||||
* `keepalived-formula <https://github.com/saltstack-formulas/keepalived-formula>`_
|
||||
* `nginx-formula <https://github.com/saltstack-formulas/nginx-formula>`_
|
||||
* `postgres-formula <https://github.com/saltstack-formulas/postgres-formula>`_
|
||||
* `prometheus-formula <https://github.com/saltstack-formulas/prometheus-formula>`_
|
||||
* `rkhunter-formula <https://github.com/saltstack-formulas/rkhunter-formula>`_
|
||||
* `salt-formula <https://github.com/saltstack-formulas/salt-formula>`_
|
||||
* `syslog-ng-formula <https://github.com/saltstack-formulas/syslog-ng-formula>`_
|
||||
* `systemd-formula <https://github.com/saltstack-formulas/systemd-formula>`_
|
||||
* `ufw-formula <https://github.com/saltstack-formulas/ufw-formula>`_
|
||||
* `vault-formula <https://github.com/saltstack-formulas/vault-formula>`_
|
||||
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
`Documentation contributing guidelines <CONTRIBUTING_DOCS.rst>`_
|
||||
@ -1,96 +0,0 @@
|
||||
.. _contributing_docs:
|
||||
|
||||
Contributing documentation
|
||||
==========================
|
||||
|
||||
|docs|
|
||||
|
||||
.. |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
|
||||
|
||||
Toolchain
|
||||
^^^^^^^^^
|
||||
|
||||
The documentation for this formula is written in
|
||||
`reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
|
||||
(also known as RST, ReST, or reST).
|
||||
It is built by
|
||||
`Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
|
||||
and hosted on
|
||||
`Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
|
||||
|
||||
Adding a new page
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Adding a new page involves two steps:
|
||||
|
||||
#. Use the
|
||||
: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``.
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _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 <https://github.com/miyakogi/m2r#restrictions>`_
|
||||
we are using for some of the pages of this documentation.
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. _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.
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user