document the migration process and update the docs a bit

stylize the docs, and document the migration process, specifically
calling out the changes to the Enforcer class, which now required
an oslo.config config object to be passed in.

implements bp graduate-policy

Change-Id: Ief4395f3312b90adea1f05903b9498b730663a74

doc/source/index.rst

@@ -2,8 +2,6 @@
  oslo.policy
 =============
 
-oslo.policy library
-
 Contents
 ========
 
@@ -22,4 +20,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

doc/source/installation.rst

@@ -5,3 +5,8 @@
 At the command line::
 
     $ pip install oslo.policy
+
+Or, if you want to use it in a virtualenvwrapper::
+
+    $ mkvirtualenv oslo.policy
+    $ pip install oslo.policy

doc/source/usage.rst

@@ -2,6 +2,38 @@
  Usage
 =======
 
-To use oslo.policy in a project::
+To use oslo.policy in a project, import the relevant module. For
+example::
 
-    import oslo_policy
+    from oslo_policy import policy
+
+Migrating to oslo.policy
+========================
+
+Applications using the incubated version of the policy code from Oslo aside
+from changing the way the library is imported, may need to make some extra
+changes.
+
+Changes to Enforcer Initialization
+----------------------------------
+
+The ``oslo.policy`` library no longer assumes a global configuration object is
+available. Instead the :py:class:`oslo_policy.policy.Enforcer` class has been
+changed to expect the consuming application to pass in an ``oslo.config``
+configuration object.
+
+When using policy from oslo-incubator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    enforcer = policy.Enforcer(policy_file=_POLICY_PATH)
+
+When using oslo.policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    from keystone import config
+    CONF = config.CONF
+    enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)