From 1fdfb3b8a1ba9d0806fd2cce98b464a337aef11d Mon Sep 17 00:00:00 2001
From: Doug Hellmann <doug.hellmann@dreamhost.com>
Date: Fri, 31 Jan 2014 08:35:51 -0800
Subject: [PATCH] Add docs for types

Add a page to pull in the docstrings for the option types,
and make the docstring changes in the module necessary for
that to work properly.

Also fix a formatting issue in the docs for the cfg module.

Change-Id: Ib1cf24e59ecc3592d3b703f99659f4a0fdbc7f5c
---
 doc/source/index.rst |  1 +
 doc/source/types.rst |  6 ++++++
 oslo/config/cfg.py   | 18 +++++++++++-------
 oslo/config/types.py |  7 +++++++
 4 files changed, 25 insertions(+), 7 deletions(-)
 create mode 100644 doc/source/types.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0a04a62e..4739bf02 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,6 +12,7 @@ Contents
 
    cfg
    opts
+   types
    configopts
    helpers
    parser
diff --git a/doc/source/types.rst b/doc/source/types.rst
new file mode 100644
index 00000000..57433efa
--- /dev/null
+++ b/doc/source/types.rst
@@ -0,0 +1,6 @@
+---------------------------
+Option Types and Validation
+---------------------------
+
+.. automodule:: oslo.config.types
+   :members:
diff --git a/oslo/config/cfg.py b/oslo/config/cfg.py
index b5485b4a..94c4c3ff 100644
--- a/oslo/config/cfg.py
+++ b/oslo/config/cfg.py
@@ -21,6 +21,7 @@ The schema for each option is defined using the Opt class or its sub-classes,
 e.g.:
 
 ::
+
     from oslo.config import cfg
     from oslo.config import types
 
@@ -764,7 +765,9 @@ if six.PY3:
 
 class DeprecatedOpt(object):
 
-    """Represents a Deprecated option. Here's how you can use it
+    """Represents a Deprecated option.
+
+    Here's how you can use it::
 
         oldopts = [cfg.DeprecatedOpt('oldfoo', group='oldgroup'),
                    cfg.DeprecatedOpt('oldfoo2', group='oldgroup2')]
@@ -772,12 +775,13 @@ class DeprecatedOpt(object):
         cfg.CONF.register_opt(cfg.StrOpt('foo', deprecated_opts=oldopts),
                                group='blaa')
 
-        Multi-value options will return all new and deprecated
-        options.  For single options, if the new option is present
-        ("[blaa]/foo" above) it will override any deprecated options
-        present.  If the new option is not present and multiple
-        deprecated options are present, the option corresponding to
-        the first element of deprecated_opts will be chosen.
+    Multi-value options will return all new and deprecated
+    options.  For single options, if the new option is present
+    ("[blaa]/foo" above) it will override any deprecated options
+    present.  If the new option is not present and multiple
+    deprecated options are present, the option corresponding to
+    the first element of deprecated_opts will be chosen.
+
     """
 
     def __init__(self, name, group=None):
diff --git a/oslo/config/types.py b/oslo/config/types.py
index bd800243..67fcd30d 100644
--- a/oslo/config/types.py
+++ b/oslo/config/types.py
@@ -14,6 +14,13 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""Type conversion and validation classes for configuration options.
+
+Use these classes as values for the `type` argument to
+:class:`oslo.config.cfg.Opt` and its subclasses.
+
+"""
+
 
 class String(object):