Merge pull request #36 from xakraz/master

docs: Update README and add GitHub action

Author: vincent-zurczak

.github/workflows/toc.yaml

@@ -0,0 +1,13 @@
+name: TOC Generator
+
+on:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  generateTOC:
+    name: TOC Generator
+    runs-on: ubuntu-latest
+    steps:
+      - uses: technote-space/toc-generator@v4

README.md

@@ -11,25 +11,31 @@ This kind of test is the ultimate set of verifications to run for a project, lon
 
 ## Table of Contents
 
-* [Objectives](#objectives)
-* [Examples](#examples)
-  * [Test files and result](#test-files-and-result)
-  * [Working with Kubectl or OC commands](#working-with-kubectl-or-oc-commands)
-  * [Other Examples](#other-examples)
-* [Usage](#usage)
-  * [Setup](#setup)
-  * [Executing tests by hand](#executing-tests-by-hand)
-  * [Continuous Integration](#continuous-integration)
-* [Syntax Reference](#syntax-reference)
-  * [Counting Resources](#counting-resources)
-  * [Verifying Property Values](#verifying-property-values)
-  * [Property Names](#property-names)
-* [Errors](#errors)
-  * [Error Codes](#error-codes)
-  * [Debugging Tests](#debugging-tests)
-  * [Linting](#linting)
-  * [Tips](#tips)
-* [Beyond K8s assertions](#beyond-k8s-assertions)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!-- param::isNotitle::true:: -->
+
+- [Objectives](#objectives)
+- [Examples](#examples)
+  - [Test files and result](#test-files-and-result)
+  - [Working with Kubectl or OC commands](#working-with-kubectl-or-oc-commands)
+  - [Other Examples](#other-examples)
+- [Usage](#usage)
+  - [Manual Setup](#manual-setup)
+  - [Docker Setup](#docker-setup)
+  - [Continuous Integration](#continuous-integration)
+- [Syntax Reference](#syntax-reference)
+  - [Counting Resources](#counting-resources)
+  - [Verifying Property Values](#verifying-property-values)
+  - [Property Names](#property-names)
+- [Errors](#errors)
+  - [Error Codes](#error-codes)
+  - [Debugging Tests](#debugging-tests)
+  - [Linting](#linting)
+  - [Tips](#tips)
+- [Beyond K8s assertions](#beyond-k8s-assertions)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 
 ## Objectives
@@ -123,7 +129,7 @@ Since this project works with BATS, you can use **setup** and **teardown**
 functions to prepare and clean after every test in a file.
 
 
-## Working with Kubectl or OC commands
+### Working with Kubectl or OC commands
 
 If you are working with a native Kubernetes cluster.
 
@@ -177,7 +183,7 @@ verify "there are 2 pods named 'nginx'"
 ```
 
 
-## Other Examples
+### Other Examples
 
 Examples are available under [the eponym directory](examples/ci).  
 It includes...
@@ -278,11 +284,14 @@ verify "there are <number> <resource-type> named '<regular-expression>'"
 *resource-type* is one of the K8s ones (e.g. `pods`, `po`, `services`, `svc`...).  
 See [https://kubernetes.io/docs/reference/kubectl/overview/#resource-types](https://kubernetes.io/docs/reference/kubectl/overview/#resource-types) for a complete reference.
 
-This simple assertion may fail sometimes.  
-As an example, if you count the number of PODs, run your test and then kill the POD, they will still
-be listed, with the TERMINATING state. So, most of the time, you will want to verify the number of instances
-with a given property value. Example: count the number of PODs with a given name pattern and having the `started` status.
-Hence this additional syntax.
+
+> :warning: This simple assertion may fail sometimes.
+>
+> As an example, if you count the number of PODs, run your test and then kill the POD, they will still be listed, with the `TERMINATING` state.
+>
+> So, most of the time, you will want to verify the number of instances with a given property value. Example: count the number of PODs with a given name pattern and having the `started` status.
+
+Hence this additional syntax (using [next section](#verifying-property-values) documentation to verify additionnal properties):
 
 ```bash
 # Expecting a given number of instances
@@ -291,14 +300,14 @@ try "at most <number> times every <number>s \
 	with '<property-name>' being '<expected-value>'"
 ```
 
-This is a checking loop.  
+:pushpin: This assertion is useful for PODs, whose life cycle changes take time.  
+For services, you may directly use the simple count assertions.
+
+This is a checking loop.
 It breaks the loop if as soon as the assertion is verified. If it reaches the end of the loop
 without having been verified, an error is thrown. Please, refer to [this section](#property-names) for details
 about the property names.
 
-This assertion is useful for PODs, whose life cycle changes take time.  
-For services, you may directly use the simple count assertions.
-
 
 ### Verifying Property Values
 
@@ -321,13 +330,13 @@ It breaks the loop if as soon as the assertion is verified. If it reaches the en
 without having been verified, an error is thrown. Please, refer to [this section](#property-names) for details
 about the property names.
 
-This assertion verifies all the instances have this property value.
-But unlike the assertion type to count resources, you do not verify how many instances have this value. Notice however that **if it finds 0 item verifying the property, the assertion fails**.
+:memo: This assertion verifies _all the instances_ have this property value.
+But unlike the assertion type to [count resources](#counting-resources), you do not verify _how many instances_ have this value. Notice however that **if it finds 0 item verifying the property, the assertion fails**.
 
 
 ### Property Names
 
-In all assertions, *property-name* if one of the column names supported by K8s.  
+In all assertions, *property-name* is one of the column names supported by K8s.  
 See https://kubernetes.io/docs/reference/kubectl/overview/#custom-columns  
 You can also find column names by using `kubectl get <resource-type> -o custom-columns=ALL:*`.