Fix up documentation files

Fix documentation files so sphinx does not complain about
missing headers or invalid include directives.

Change-Id: Ife520469f62ea048c552b7610b1da5c1bd703d75

README.rst

@@ -34,9 +34,37 @@ in the openstack-infra/config git repository and add sections like:
        branch-designator: ''
        branch-override: default
 
-To the ``jobs`` list for your project. Refer to
+to the ``jobs`` list for your project. Refer to
 https://review.openstack.org/#/c/76381 for an example.
 
+Then update ``modules/openstack_project/files/zuul/layout.yaml`` by
+adding the new check test to the global list of jobs (to make it
+non-voting to start), and then to your project and to oslo.test.
+
+::
+
+  - name: check-oslo.test-dsvm-oslo.messaging
+    voting: false
+
+::
+
+    - name: openstack/oslo.messaging
+      ...
+      check:
+      ...
+        - check-oslo.test-dsvm-oslo.messaging
+      ...
+
+::
+
+    - name: openstack/oslo.test
+      ...
+      check:
+      ...
+        - check-oslo.test-dsvm-oslo.messaging
+      ...
+
+
 Locally
 -------
 

doc/source/contributing.rst

@@ -1 +1,5 @@
+==============
+ Contributing
+==============
+
 .. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to 's documentation!
+Welcome to oslo.test's documentation!
-========================================================
+=====================================
 
 Contents:
 

doc/source/installation.rst

@@ -4,9 +4,4 @@ Installation
 
 At the command line::
 
-    $ pip install 
+    $ pip install oslotest
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv 
-    $ pip install 

doc/source/readme.rst

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

doc/source/usage.rst

@@ -4,4 +4,10 @@ Usage
 
 To use  in a project::
 
-	import test
+    from oslotest import base
+
+
+    class MyTest(base.BaseTestCase):
+
+        def test_something(self):
+            self.assertTrue(True)