diff --git a/doc/source/conf.py b/doc/source/conf.py
index cff3f2e3aa6381483fee823ab6b66e57c1a86f9c..90312030b531d60c55d49ee53d232ca338ad510e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',
     'oslosphinx',
     'oslo_config.sphinxext',
 ]
@@ -40,6 +40,7 @@ master_doc = 'index'
 # General information about the project.
 project = u'oslo.versionedobjects'
 copyright = u'2014, OpenStack Foundation'
+source_tree = 'http://git.openstack.org/cgit/openstack/%s/tree' % project
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -48,6 +49,12 @@ add_function_parentheses = True
 # unit titles (such as .. function::).
 add_module_names = True
 
+# Shortened external links.
+extlinks = {
+    'example': (source_tree +
+                '/%s/examples/%%s.py' % project.replace(".", "_"), ''),
+}
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5317d77e81d44ffe11c9b1cc48b7d7f377e82b6a
--- /dev/null
+++ b/doc/source/examples.rst
@@ -0,0 +1,23 @@
+==========
+ Examples
+==========
+
+IOT lightbulb
+=============
+
+.. note::
+
+    Full source located at :example:`iot_bulb`.
+
+.. literalinclude:: ../../oslo_versionedobjects/examples/iot_bulb.py
+    :language: python
+    :linenos:
+    :lines: 14-
+
+Expected (or similar) output::
+
+	The __str__() output of this new object: IOTLightbulb(manufactured_on=2017-03-15T23:25:01Z,serial='abc-123')
+	The 'serial' field of the object: abc-123
+	Primitive representation of this object: {'versioned_object.version': '1.0', 'versioned_object.changes': ['serial', 'manufactured_on'], 'versioned_object.name': 'IOTLightbulb', 'versioned_object.data': {'serial': u'abc-123', 'manufactured_on': '2017-03-15T23:25:01Z'}, 'versioned_object.namespace': 'versionedobjects.examples'}
+	The __str__() output of this new (reconstructed) object: IOTLightbulb(manufactured_on=2017-03-15T23:25:01Z,serial='abc-123')
+	After serial number change, the set of fields that have been mutated is: set(['serial'])
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 94dc98ee247da3363f4ee8f5e40733a2844b7bcd..cf1e3557fbf69c65f8e09a185ff95b07088a036b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -22,6 +22,7 @@ Contents
    installation
    api/index
    usage
+   examples
    opts
    contributing
 
diff --git a/oslo_versionedobjects/examples/__init__.py b/oslo_versionedobjects/examples/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/oslo_versionedobjects/examples/iot_bulb.py b/oslo_versionedobjects/examples/iot_bulb.py
new file mode 100644
index 0000000000000000000000000000000000000000..b5160bc9bf273aade0010225bf0bd7acee361383
--- /dev/null
+++ b/oslo_versionedobjects/examples/iot_bulb.py
@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from datetime import datetime
+
+from oslo_versionedobjects import base
+from oslo_versionedobjects import fields as obj_fields
+
+# INTRO: This example shows how a object (a plain-old-python-object) with
+# some associated fields can be used, and some of its built-in methods can
+# be used to convert that object into a primitive and back again (as well
+# as determine simple changes on it.
+
+
+# Ensure that we always register our object with an object registry,
+# so that it can be deserialized from its primitive form.
+@base.VersionedObjectRegistry.register
+class IOTLightbulb(base.VersionedObject):
+    """Simple light bulb class with some data about it."""
+
+    VERSION = '1.0'  # Initial version
+
+    #: Namespace these examples will use.
+    OBJ_PROJECT_NAMESPACE = 'versionedobjects.examples'
+
+    #: Required fields this object **must** declare.
+    fields = {
+        'serial': obj_fields.StringField(),
+        'manufactured_on': obj_fields.DateTimeField(),
+    }
+
+# Now do some basic operations on a light bulb.
+bulb = IOTLightbulb(serial='abc-123', manufactured_on=datetime.now())
+print("The __str__() output of this new object: %s" % bulb)
+print("The 'serial' field of the object: %s" % bulb.serial)
+bulb_prim = bulb.obj_to_primitive()
+print("Primitive representation of this object: %s" % bulb_prim)
+
+# Now convert the primitive back to an object (isn't it easy!)
+bulb = IOTLightbulb.obj_from_primitive(bulb_prim)
+
+bulb.obj_reset_changes()
+print("The __str__() output of this new (reconstructed)"
+      " object: %s" % bulb)
+
+# Mutating a field and showing what changed.
+bulb.serial = 'abc-124'
+print("After serial number change, the set of fields that"
+      " have been mutated is: %s" % bulb.obj_what_changed())