rearrange existing documentation to fit the new standard layout

Minor formatting improvements found during the document check
are also done.

Change-Id: I55d582100c40961a5b0f5ec4b2ea9a55f2d8d8a1

CONTRIBUTING.rst

@@ -1,16 +1,13 @@
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in this page:
-
-   http://docs.openstack.org/infra/manual/developers.html
+http://docs.openstack.org/infra/manual/developers.html
 
 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
 the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
-
-   https://bugs.launchpad.net/oslo.versionedobjects
+https://bugs.launchpad.net/oslo.versionedobjects

doc/source/contributor/index.rst

@@ -2,4 +2,4 @@
  Contributing
 ==============
 
-.. include:: ../../CONTRIBUTING.rst
+.. include:: ../../../CONTRIBUTING.rst

doc/source/history.rst

@@ -1 +0,0 @@
-.. include:: ../../ChangeLog

doc/source/index.rst

@@ -13,29 +13,18 @@ upgrade compatibility across distributed services.
 * Source: http://git.openstack.org/cgit/openstack/oslo.versionedobjects
 * Bugs: http://bugs.launchpad.net/oslo.versionedobjects
 
-Contents
-========
+----
 
 .. toctree::
    :maxdepth: 2
 
-   installation
-   api/index
-   usage
-   examples
-   opts
-   contributing
+   install/index
+   user/index
+   configuration/index
+   reference/index
+   contributor/index
 
-Release Notes
-=============
-
-.. toctree::
-   :maxdepth: 1
-
-   history
-
-Indices and tables
-==================
+.. rubric:: Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/source/reference/index.rst

@@ -1,6 +1,6 @@
-=====
- API
-=====
+=============
+API Reference
+=============
 
 .. toctree::
    :maxdepth: 2

doc/source/user/examples.rst

@@ -9,7 +9,7 @@ IOT lightbulb
 
     Full source located at :example:`iot_bulb`.
 
-.. literalinclude:: ../../oslo_versionedobjects/examples/iot_bulb.py
+.. literalinclude:: ../../../oslo_versionedobjects/examples/iot_bulb.py
     :language: python
     :linenos:
     :lines: 14-

doc/source/user/history.rst

@@ -0,0 +1 @@
+.. include:: ../../../ChangeLog

doc/source/user/index.rst

@@ -0,0 +1,15 @@
+===========================
+Using oslo.versionedobjects
+===========================
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   examples
+
+.. history contains a lot of sections, toctree with maxdepth 1 is used.
+.. toctree::
+   :maxdepth: 1
+
+   history

oslo_versionedobjects/base.py

@@ -1129,7 +1129,7 @@ def obj_tree_get_versions(objname, tree=None):
     level object with other objects as fields. It walks the tree recursively
     to determine all the objects (by symbolic name) that could be contained
     within the top-level object, and the maximum versions of each. The result
-    is a dict like:
+    is a dict like::
 
       {'MyObject': '1.23', ... }
 

oslo_versionedobjects/fields.py

@@ -1036,7 +1036,7 @@ class UUIDField(AutoTypedField):
     your own objects/fields.py
 
     :Example:
-         .. code-block:: python
+        .. code-block:: python
 
             import oslo_versionedobjects.fields as ovo_fields
 
@@ -1049,8 +1049,8 @@ class UUIDField(AutoTypedField):
             class UUIDField(ovo_fields.AutoTypedField):
                 AUTO_TYPE = UUID()
 
-        and then in your objects use
-        ``<your_projects>.object.fields.UUIDField``.
+    and then in your objects use
+    ``<your_projects>.object.fields.UUIDField``.
 
     This will become default behaviour in the future.
     """