diff --git a/README.rst b/README.rst
index e9ef4852..9b5274c4 100644
--- a/README.rst
+++ b/README.rst
@@ -2,12 +2,11 @@
 oslo.versionedobjects
 ===================================
 
-oslo.versionedobjects library deals with DB schema being at different versions
-than the code expects, allowing services to be operated safely during upgrades.
-It enables DB independent schema by providing an abstraction layer, which
-allows us to support SQL and NoSQL Databases. oslo.versionedobjects is also
-used in RPC APIs, to ensure upgrades happen without spreading version dependent
-code across different services and projects.
+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
diff --git a/doc/source/api.rst b/doc/source/api.rst
deleted file mode 100644
index 971225e7..00000000
--- a/doc/source/api.rst
+++ /dev/null
@@ -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).
diff --git a/doc/source/api/base.rst b/doc/source/api/base.rst
new file mode 100644
index 00000000..d9c8ac09
--- /dev/null
+++ b/doc/source/api/base.rst
@@ -0,0 +1,6 @@
+=============
+ base
+=============
+
+.. automodule:: oslo_versionedobjects.base
+   :members:
diff --git a/doc/source/api/exception.rst b/doc/source/api/exception.rst
new file mode 100644
index 00000000..5dfe5740
--- /dev/null
+++ b/doc/source/api/exception.rst
@@ -0,0 +1,6 @@
+=============
+ exception
+=============
+
+.. automodule:: oslo_versionedobjects.exception
+   :members:
diff --git a/doc/source/api/fields.rst b/doc/source/api/fields.rst
new file mode 100644
index 00000000..80b87eef
--- /dev/null
+++ b/doc/source/api/fields.rst
@@ -0,0 +1,6 @@
+=============
+ fields
+=============
+
+.. automodule:: oslo_versionedobjects.fields
+   :members:
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
new file mode 100644
index 00000000..f193e3b6
--- /dev/null
+++ b/doc/source/api/index.rst
@@ -0,0 +1,9 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9f5a95fa..2bd16c2c 100644
--- a/doc/source/index.rst
+++ b/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
 
diff --git a/oslo_versionedobjects/base.py b/oslo_versionedobjects/base.py
index c14e10b3..3182d2b4 100644
--- a/oslo_versionedobjects/base.py
+++ b/oslo_versionedobjects/base.py
@@ -471,11 +471,11 @@ 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:target_version: The version string requested by the recipient
-        of the object
-        :raises: oslo_versionedobjects.exception.UnsupportedObjectError
-        if conversion is not possible for some reason
+        :param primitive: The result of :meth:`obj_to_primitive`
+        :param target_version: The version string requested by the recipient
+                               of the object
+        :raises: :exc:`oslo_versionedobjects.exception.UnsupportedObjectError`
+                 if conversion is not possible for some reason
         """
         for key, field in self.fields.items():
             if not isinstance(field, (obj_fields.ObjectField,
@@ -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"
-        NOTE: Specifying fields on recursive resets will only be
-              honored at the top level. Everything below the top
-              will reset all.
+        This is NOT "revert to previous values".
+
+        Specifying fields on recursive resets will only be honored at the top
+        level. Everything below the top will reset all.
         """
         if recursive:
             for field in self.obj_get_changes():