Ensure that doc linting is included in the linters test

The 'docs' tox target executes the doc8 lint test which may result in
failures when testing documentation builds, but OpenStack-CI does not
execute that tox target.

In order to ensure that we catch all standard documentation syntax
errors and prevent them from merging, this patch includes the docs
target in the 'linters' chain of tests.

Fixes for any failures which result from executing this test are also
included in the patch.

Change-Id: I62c4e2a01cf6f5e6c03f67022ea946b420700f85

README.rst

@@ -21,6 +21,7 @@ Required Variables
 To use this role, define the following variables:
 
 .. code-block:: yaml
+
     # password of the keystone service user for heat
     heat_service_password: "secrete"
     # password of the admin user for the keystone heat domain
@@ -62,3 +63,4 @@ This role supports two tags: ``heat-install`` and ``heat-config``
 The ``heat-install`` tag can be used to install and upgrade.
 
 The ``heat-config`` tag can be used to manage configuration.
+

doc/source/index.rst

@@ -1 +1 @@
-.. include:: ../../README.rst
+.. include:: ../../README.rst

tox.ini

@@ -181,3 +181,4 @@ commands =
     {[testenv:bashate]commands}
     {[testenv:ansible-lint]commands}
     {[testenv:ansible-syntax]commands}
+    {[testenv:docs]commands}