Merge "docs: Rework reference, usage docs"

doc/source/reference/base.rst

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

doc/source/reference/exception.rst

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

doc/source/reference/fields.rst

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

doc/source/reference/fixture.rst

@@ -1,6 +1,6 @@
-=========
- Fixture
-=========
+=============================
+oslo_versionedobjects.fixture
+=============================
 
 .. automodule:: oslo_versionedobjects.fixture
    :members:

doc/source/user/usage.rst

@@ -2,76 +2,58 @@
  Usage
 =======
 
-Incorporating oslo.versionedobjects into your projects can be accomplished in
+Incorporating *oslo.versionedobjects* into your project can be accomplished in
 the following steps:
 
-1. `Add oslo.versionedobjects to requirements`_
-2. `Create objects subdirectory and a base.py inside it`_
-3. `Create base object with the project namespace`_
-4. `Create other base objects if needed`_
-5. `Implement objects and place them in objects/\*.py`_
-6. `Implement extra fields in objects/fields.py`_
-7. `Create object registry and register all objects`_
-8. `Create and attach the object serializer`_
-9. `Implement the indirection API`_
+Initial scaffolding
+-------------------
 
+By convention, objects reside in the `<project>/objects` directory. This is the
+place from which all objects should be imported.
 
-Add oslo.versionedobjects to requirements
------------------------------------------
+Start the implementation by creating `objects/base.py` with a subclass of the
+:class:`oslo_versionedobjects.base.VersionedObject`. This class will form the
+base class for all objects in the project. You need to populate the
+``OBJ_PROJECT_NAMESPACE`` property.
 
-To use oslo.versionedobjects in an OpenStack project remember to add it to the
-requirements.txt
+.. note::
 
+    ``OBJ_SERIAL_NAMESPACE`` is used only for backward compatibility and
+    should not be set in new projects.
 
-Create objects subdirectory and a base.py inside it
----------------------------------------------------
+You may also wish to optionally include the following mixins:
 
-Objects reside in the `<project>/objects` directory and this is the place
-from which all objects should be imported.
+* :class:`oslo_versionedobjects.base.VersionedPersistentObject`
 
-Start the implementation by creating `objects/base.py` with these main
-classes:
+    A mixin class for persistent objects can be created, defining repeated
+    fields like ``created_at``, ``updated_at``. Fields are defined in the fields
+    property (which is a dict).
 
+* :class:`oslo_versionedobjects.base.VersionedObjectDictCompat`
 
-Create base object with the project namespace
----------------------------------------------
+    If objects were previously passed as dicts (a common situation), this class
+    can be used as a mixin class to support dict operations.
 
-:class:`oslo_versionedobjects.base.VersionedObject`
-
-The VersionedObject base class for the project. You have to fill up the
-`OBJ_PROJECT_NAMESPACE` property. `OBJ_SERIAL_NAMESPACE` is used only for
-backward compatibility and should not be set in new projects.
-
-
-Create other base objects if needed
------------------------------------
-
-class:`oslo_versionedobjects.base.VersionedPersistentObject`
-
-A mixin class for persistent objects can be created, defining repeated fields
-like `created_at`, `updated_at`. Fields are defined in the fields property
-(which is a dict).
-
-If objects were previously passed as dicts (a common situation), a
-:class:`oslo_versionedobjects.base.VersionedObjectDictCompat` can be used as a
-mixin class to support dict operations.
-
-Implement objects and place them in objects/\*.py
--------------------------------------------------
-
-Objects classes should be created for all resources/objects passed via RPC
-as IDs or dicts in order to:
+Once you have you base class defined, you can define your actual object
+classes. Objects classes should be created for all resources/objects passed via
+RPC as IDs or dicts in order to:
 
 * spare the database (or other resource) from extra calls
 * pass objects instead of dicts, which are tagged with their version
-* handle all object versions in one place (the `obj_make_compatible` method)
+* handle all object versions in one place (the ``obj_make_compatible`` method)
 
 To make sure all objects are accessible at all times, you should import them
-in __init__.py in the objects/ directory.
+in ``__init__.py`` in the ``objects/`` directory and expose them via
+``__all__``.
 
+Finally, you should create an object registry by subclassing
+:class:`oslo_versionedobjects.base.VersionedObjectRegistry`. The object
+registry is the place where all objects are registered. All object classes
+should be registered by the
+:attr:`oslo_versionedobjects.base.ObjectRegistry.register` class decorator.
 
-Implement extra fields in objects/fields.py
--------------------------------------------
+Using custom field types
+------------------------
 
 New field types can be implemented by inheriting from
 :class:`oslo_versionedobjects.field.Field` and overwriting the `from_primitive`
@@ -81,28 +63,14 @@ By subclassing :class:`oslo_versionedobjects.fields.AutoTypedField` you can
 stack multiple fields together, making sure even nested data structures are
 being validated.
 
-
-Create object registry and register all objects
------------------------------------------------
-
-:class:`oslo_versionedobjects.base.VersionedObjectRegistry`
-
-The place where all objects are registered. All object classes should be
-registered by the :attr:`oslo_versionedobjects.base.ObjectRegistry.register`
-class decorator.
-
-
-
-Create and attach the object serializer
----------------------------------------
-
-:class:`oslo_versionedobjects.base.VersionedObjectSerializer`
+Configure serialization
+-----------------------
 
 To transfer objects by RPC, subclass the
 :class:`oslo_versionedobjects.base.VersionedObjectSerializer` setting the
 OBJ_BASE_CLASS property to the previously defined Object class.
 
-Connect the serializer to oslo_messaging:
+For example, to use a custom serializer with `oslo_messaging`__:
 
 .. code:: python
 
@@ -110,22 +78,23 @@ Connect the serializer to oslo_messaging:
    target = messaging.Target(topic=topic, server=server)
    self._server = messaging.get_rpc_server(transport, target, handlers, serializer=serializer)
 
+.. __: https://docs.openstack.org/oslo.messaging/latest/
 
 Implement the indirection API
 -----------------------------
 
-:class:`oslo_versionedobjects.base.VersionedObjectIndirectionAPI`
+*oslo.versionedobjects* supports "remotable" method calls. These are calls of
+the object methods and classmethods which can be executed locally or remotely
+depending on the configuration. Setting the ``indirection_api`` as a property
+of an object relays the calls to decorated methods through the defined RPC API.
+The attachment of the ``indirection_api`` should be handled by configuration at
+startup time.
 
-oslo.versionedobjects supports `remotable` method calls. These are calls
-of the object methods and classmethods which can be executed locally or
-remotely depending on the configuration. Setting the indirection_api as a
-property of an object relays the calls to decorated methods through the
-defined RPC API. The attachment of the indirection_api should be handled
-by configuration at startup time.
-
-Second function of the indirection API is backporting. When the object
-serializer attempts to deserialize an object with a future version, not
-supported by the current instance, it calls the object_backport method in an
-attempt to backport the object to a version which can then be handled as
+The second function of the indirection API is backporting. When the object
+serializer attempts to deserialize an object with a future version not
+supported by the current instance, it calls the ``object_backport`` method in
+an attempt to backport the object to a version which can then be handled as
 normal.
 
+The :class:`oslo_versionedobjects.base.VersionedObjectIndirectionAPI` class
+provides a base class for implementing your own indirection API.