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

@@ -12,6 +12,7 @@ Contents
 
    cfg
    opts
+   types
    configopts
    helpers
    parser

doc/source/types.rst

@@ -0,0 +1,6 @@
+---------------------------
+Option Types and Validation
+---------------------------
+
+.. automodule:: oslo.config.types
+   :members:

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
+    Multi-value options will return all new and deprecated
-        options.  For single options, if the new option is present
+    options.  For single options, if the new option is present
-        ("[blaa]/foo" above) it will override any deprecated options
+    ("[blaa]/foo" above) it will override any deprecated options
-        present.  If the new option is not present and multiple
+    present.  If the new option is not present and multiple
-        deprecated options are present, the option corresponding to
+    deprecated options are present, the option corresponding to
-        the first element of deprecated_opts will be chosen.
+    the first element of deprecated_opts will be chosen.
+
     """
 
     def __init__(self, name, group=None):

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):