Enhance documentation

Rewrite README.rst and copy it to doc/source/index.rst to add a little
bit more content.

Generate documentation for APIs. fixture, safe_utils and test submodules
are not documented.

Fix indentation in obj_reset_changes() docstring.

Fix formatting of obj_make_list() docstring.

Co-Authored-By: Dan Smith <dansmith@redhat.com>
Change-Id: I8110919de072c5a5139e3797f256925c92656117

README.rst

@@ -2,12 +2,11 @@
 oslo.versionedobjects
 ===================================
 
-oslo.versionedobjects library deals with DB schema being at different versions
+The oslo.versionedobjects library provides a generic versioned object model
-than the code expects, allowing services to be operated safely during upgrades.
+that is RPC-friendly, with inbuilt serialization, field typing, and remotable
-It enables DB independent schema by providing an abstraction layer, which
+method calls. It can be used to define a data model within a project
-allows us to support SQL and NoSQL Databases. oslo.versionedobjects is also
+independent of external APIs or database schema for the purposes of providing
-used in RPC APIs, to ensure upgrades happen without spreading version dependent
+upgrade compatibility across distributed services.
-code across different services and projects.
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/oslo.versionedobjects

doc/source/api.rst

@@ -1,12 +0,0 @@
-=====
- API
-=====
-
-.. Use autodoc directives to describe the *public* modules and classes
-   in the library.
-
-   If the modules are completely unrelated, create an api subdirectory
-   and use a separate file for each (see oslo.utils).
-
-   If there is only one submodule, a single api.rst file like this
-   sufficient (see oslo.i18n).

doc/source/api/base.rst

@@ -0,0 +1,6 @@
+=============
+ base
+=============
+
+.. automodule:: oslo_versionedobjects.base
+   :members:

doc/source/api/exception.rst

@@ -0,0 +1,6 @@
+=============
+ exception
+=============
+
+.. automodule:: oslo_versionedobjects.exception
+   :members:

doc/source/api/fields.rst

@@ -0,0 +1,6 @@
+=============
+ fields
+=============
+
+.. automodule:: oslo_versionedobjects.fields
+   :members:

doc/source/api/index.rst

@@ -0,0 +1,9 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

doc/source/index.rst

@@ -2,7 +2,16 @@
  oslo.versionedobjects
 =======================
 
-oslo.versionedobjects library
+The oslo.versionedobjects library provides a generic versioned object model
+that is RPC-friendly, with inbuilt serialization, field typing, and remotable
+method calls. It can be used to define a data model within a project
+independent of external APIs or database schema for the purposes of providing
+upgrade compatibility across distributed services.
+
+* Free software: Apache license
+* Documentation: http://docs.openstack.org/developer/oslo.versionedobjects
+* Source: http://git.openstack.org/cgit/openstack/oslo.versionedobjects
+* Bugs: http://bugs.launchpad.net/oslo.versionedobjects
 
 Contents
 ========
@@ -11,7 +20,7 @@ Contents
    :maxdepth: 2
 
    installation
-   api
+   api/index
    usage
    contributing
 

oslo_versionedobjects/base.py

@@ -471,10 +471,10 @@ class VersionedObject(object):
           if the requested version of this object is older than the version
           where the new dependent object was added.
 
-        :param:primitive: The result of self.obj_to_primitive()
+        :param primitive: The result of :meth:`obj_to_primitive`
-        :param:target_version: The version string requested by the recipient
+        :param target_version: The version string requested by the recipient
                                of the object
-        :raises: oslo_versionedobjects.exception.UnsupportedObjectError
+        :raises: :exc:`oslo_versionedobjects.exception.UnsupportedObjectError`
                  if conversion is not possible for some reason
         """
         for key, field in self.fields.items():
@@ -570,10 +570,10 @@ class VersionedObject(object):
                           any sub-objects within the list of fields
                           being reset.
 
-        NOTE: This is NOT "revert to previous values"
+        This is NOT "revert to previous values".
-        NOTE: Specifying fields on recursive resets will only be
+
-              honored at the top level. Everything below the top
+        Specifying fields on recursive resets will only be honored at the top
-              will reset all.
+        level. Everything below the top will reset all.
         """
         if recursive:
             for field in self.obj_get_changes():