From a5bae1efe0066881e153cc060c1198e1c76d0eed Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Fri, 22 Feb 2019 16:38:50 +0000 Subject: [PATCH 1/4] feat(toc): use `markdown-toc` directly to update inline * https://github.com/jonschlinkert/markdown-toc - Generate a markdown TOC (table of contents) for any markdown files. --- .travis.yml | 6 ++++++ CONTRIBUTING.md | 5 +++++ README.rst | 2 ++ TOFS_pattern.md | 5 +++++ 4 files changed, 18 insertions(+) diff --git a/.travis.yml b/.travis.yml index b0c6c21c..6ab06f01 100644 --- a/.travis.yml +++ b/.travis.yml @@ -45,6 +45,12 @@ jobs: - go get github.com/myii/maintainer - maintainer contributor + # Update Tables of Content in the relevant `.md` files + - npm install markdown-toc -D + - markdown-toc -i CONTRIBUTING.md + # - markdown-toc -i README.md + - markdown-toc -i TOFS_pattern.md + # Install all dependencies required for `semantic-release` - npm install @semantic-release/changelog@3 -D - npm install @semantic-release/exec@3 -D diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26f43cbe..3919bcd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,10 @@ # How to contribute +
Table of Contents
+ + +
+ ## Commit message formatting ### Automation of multiple processes diff --git a/README.rst b/README.rst index db46bdb2..f679e303 100644 --- a/README.rst +++ b/README.rst @@ -12,6 +12,8 @@ template-formula 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. +.. contents:: **Table of Contents** + **NOTE** See the full `Salt Formulas installation and usage instructions diff --git a/TOFS_pattern.md b/TOFS_pattern.md index 4ecb31dd..c133e91d 100644 --- a/TOFS_pattern.md +++ b/TOFS_pattern.md @@ -7,6 +7,11 @@ Modified by Daniel Dehennin All that follows is a proposal based on my experience with [Saltstack](http://www.saltstack.com/). 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. +
Table of Contents
+ + +
+ ## Usage of values in pillar vs templates in file_roots From 5f2d7894abeb119b480ebc18d18afb9a7a38c8ba Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Sat, 23 Feb 2019 06:57:00 +0000 Subject: [PATCH 2/4] docs(readme): convert note into a heading --- README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index f679e303..1d5d1125 100644 --- a/README.rst +++ b/README.rst @@ -14,9 +14,10 @@ start on a new formula and it serves as a style guide. .. contents:: **Table of Contents** -**NOTE** +General notes +============= -See the full `Salt Formulas installation and usage instructions +See the full `SaltStack Formulas installation and usage instructions `_. If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section From 45ccaf68bd0eb8f44b11eeab8fdd106f456bede0 Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Sat, 23 Feb 2019 06:57:59 +0000 Subject: [PATCH 3/4] docs(contributing): add basic introductory text before the TOC --- CONTRIBUTING.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3919bcd7..b5bf99bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,8 @@ # 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. +
Table of Contents
@@ -9,7 +12,7 @@ ### Automation of multiple processes -This repo 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. +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). @@ -34,7 +37,7 @@ So based on the example above: ### Linting commit messages in Travis CI -This repo uses [`commitlint`](https://github.com/conventional-changelog/commitlint) for checking commit messages during CI testing. +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). From abcb6ef399ec0d1021812015b1a2e38f2a223d26 Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Sat, 23 Feb 2019 15:03:22 +0000 Subject: [PATCH 4/4] docs(contributing): modify quoted heading to prevent TOC inclusion --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5bf99bf..56c94ae1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ type(scope): subject Besides the version bump, the changelog and release notes are formatted accordingly. So based on the example above: -> ### Documentation +>

Documentation

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