Merge pull request #29 from n-rodriguez/wip/doc

docs(readme): improve readme sections

docs/README.rst

@@ -14,7 +14,7 @@ vault-formula
    :scale: 100%
    :target: https://github.com/semantic-release/semantic-release
 
-Formulas for working with `Vault <http://www.vaultproject.io>`_
+Formulas for working with `Vault <http://www.vaultproject.io>`_.
 
 .. contents:: **Table of Contents**
 
@@ -40,19 +40,19 @@ Contributing to this repo
 Please see :ref:`How to contribute <CONTRIBUTING>` for more details.
 
 Available states
-================
+----------------
 
 .. contents::
     :local:
 
 ``vault``
----------
+^^^^^^^^^
 
 Install the vault binary
 
 
 ``vault.server``
-----------------
+^^^^^^^^^^^^^^^^
 
 Install and configure the vault server
 
@@ -79,27 +79,38 @@ To use it, just include *vault* in your *top.sls*, and configure it using pillar
       max_lease_ttl: 768h
 
 Issues
-======
+-------
 
 Vault `v0.10.0 <https://github.com/hashicorp/vault/blob/master/CHANGELOG.md#0100-april-10th-2018>`_ introduces a revamped versioned kv backend (version 2), with a breaking change in the paths used to read/write data. This backend is enabled by default when dev mode is enabled.
 
 The Salt execution modules are not compatible with this new backend, therefore if you intend to access Vault in dev mode using the Salt modules, it's suggested to use an outdated, but compatible version of Vault by setting a pillar value e.g. ``version: 0.9.6``.
 
 Testing
-=======
+-------
 
-Testing is done with `Test Kitchen <http://kitchen.ci/>`_
-for machine setup and `inspec <https://github.com/chef/inspec/>`_
-for integration tests.
+Linux testing is done with ``kitchen-salt``.
 
-Requirements
-------------
+``kitchen converge``
+^^^^^^^^^^^^^^^^^^^^
 
-* Ruby
-* Docker
+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``
+^^^^^^^^^^^^^^^^^
 
-    gem install bundler
-    bundle install
-    bundle exec kitchen test all
+Gives you SSH access to the instance for manual testing.