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: Icab9cde9110e4ea485a84ab5ba3cf2355c57797b

README.rst

@@ -1,5 +1,6 @@
-OpenStack pip lockdown
-######################
+OpenStack pip_lock_down
+#######################
+
 :tags: openstack, pip, lockdown, cloud, ansible
 :category: \*nix
 
@@ -21,3 +22,4 @@ using pip are from a known repository of packages.
 
 
 This was intended for use with a repository built from the repo role.
+

doc/source/index.rst

@@ -1,22 +1 @@
-pip_lock_down Docs
-=============
-
-Role to lock pip down to a particular links repo. This will create a
-``.pip.conf`` which will ensure that the only python packages installed when
-using pip are from a known repository of packages.
-
-
-Basic Role Example
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: yaml
-
-    - name: Basic lxc host setup
-      hosts: host_group
-      user: root
-      roles:
-        - { role: "pip_lock_down", tags: [ "pip-lock-down" ] }
-      vars:
-        pip_links:
-          name: openstack-release
-          link: https://openstack-hostname.something/python_packages/master
+.. include:: ../../README.rst

tox.ini

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