From 92a979b6896a31ec2c262ccdd1c7e86e812d6adc Mon Sep 17 00:00:00 2001
From: "George Silvis, III" <george.iii.silvis@gmail.com>
Date: Thu, 18 Aug 2016 14:51:22 -0400
Subject: [PATCH] Add usage example to documentation

This example is cobbled together from Keystone's use-case.

Change-Id: Ib0ab0926f2cc86e2b45dfccbf8f73c638ec90a6f
---
 doc/source/usage.rst | 46 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 675cc7bb..a5fe7ceb 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,6 +2,48 @@
  Usage
 =======
 
-To use oslo.cache in a project::
+A simple example of oslo.cache in use::
 
-    import oslo_cache
+    from oslo_cache import core as cache
+    from oslo_config import cfg
+
+    CONF = cfg.CONF
+
+    caching = cfg.BoolOpt('caching', default=True)
+    cache_time = cfg.IntOpt('cache_time', default=3600)
+    CONF.register_opts([caching, cache_time], "feature-name")
+
+    cache.configure(CONF)
+    example_cache_region = cache.create_region()
+    MEMOIZE = cache.get_memoization_decorator(
+        CONF, example_cache_region, "feature-name")
+
+    # Load config file here
+
+    cache.configure_cache_region(example_cache_region)
+
+
+    @MEMOIZE
+    def f(x):
+        print x
+        return x
+
+An example config file for this is::
+
+    [cache]
+    enabled = true
+    backend = dogpile.cache.memory
+
+    [feature-name]
+    caching = True
+    cache_time = 7200
+
+There is some subtlety in the order of the calls in the example above.  The
+requirements are: ``configure`` must be done first; ``create_region`` must be
+before both ``get_memoization_decorator`` and ``configure_cache_region``
+(because they use the output);  the config file must be fully loaded before
+``configure_cache_region`` is called; all these calls must complete before a
+decorated function is actually invoked.  In principle, there are several
+different orders this can happen in.  In practice, the decorator will be used
+at import time, and the config file will be loaded later, so the above order is
+the only possible one.