docs(readme): improve readme sections

docs/README.rst

@@ -14,8 +14,7 @@ nginx-formula
    :scale: 100%
    :target: https://github.com/semantic-release/semantic-release
 
-Formula to set up and configure
-`NGINX <https://www.nginx.com/>`_.
+Formula to set up and configure `NGINX <https://www.nginx.com/>`_.
 
 .. list-table::
    :name: banner-breaking-changes-v1.0.0
@@ -69,13 +68,13 @@ Contributing to this repo
 Please see :ref:`How to contribute <CONTRIBUTING>` for more details.
 
 Available states
-================
+----------------
 
 .. contents::
     :local:
 
 ``nginx``
----------
+^^^^^^^^^
 
 Meta-state for inclusion of all states.
 
@@ -83,45 +82,75 @@ Meta-state for inclusion of all states.
 first available in the Helium release.
 
 ``nginx.pkg``
--------------
+^^^^^^^^^^^^^
 
 Installs nginx from package, from the distribution repositories, the official nginx repo or the ppa from Launchpad.
 
 ``nginx.src``
--------------
+^^^^^^^^^^^^^
 
 Builds and installs nginx from source.
 
 ``nginx.certificates``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Manages the deployment of nginx certificates.
 
 ``nginx.config``
-----------------
+^^^^^^^^^^^^^^^^
 
 Manages the nginx main server configuration file.
 
 ``nginx.service``
------------------
+^^^^^^^^^^^^^^^^^
 
 Manages the startup and running state of the nginx service.
 
 ``nginx.servers_config``
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Manages virtual host files. This state only manages the content of the files
 and does not bind them to service calls.
 
 ``nginx.servers``
------------------
+^^^^^^^^^^^^^^^^^
 
 Manages nginx virtual hosts files and binds them to service calls.
 
 ``nginx.passenger``
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 Installs and configures Phusion Passenger module for nginx. You need to enable
 the upstream phusion passenger repository with `install_from_phusionpassenger: true`.
 Nginx will also be installed from that repository, as it needs to be modified to
 allow the passenger module to work.
+
+Testing
+-------
+
+Linux testing is done with ``kitchen-salt``.
+
+``kitchen converge``
+^^^^^^^^^^^^^^^^^^^^
+
+Creates the docker instance and runs the ``template`` main state, ready for testing.
+
+``kitchen verify``
+^^^^^^^^^^^^^^^^^^
+
+Runs the ``inspec`` tests on the actual instance.
+
+``kitchen destroy``
+^^^^^^^^^^^^^^^^^^^
+
+Removes the docker instance.
+
+``kitchen test``
+^^^^^^^^^^^^^^^^
+
+Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
+
+``kitchen login``
+^^^^^^^^^^^^^^^^^
+
+Gives you SSH access to the instance for manual testing.