Add versionutils to API documentation

Add an automodule directive for the new module.

Clean up the existing docstring so it renders a bit more nicely.

Update the usage page to refer to the new location of versionutils.

Change-Id: Ib732509186e56ed2b39638129e2ec4272da1aa9d

doc/source/api/versionutils.rst

@@ -0,0 +1,6 @@
+=======================
+ oslo_log.versionutils
+=======================
+
+.. automodule:: oslo_log.versionutils
+   :members:

doc/source/index.rst

@@ -20,12 +20,9 @@ API Documentation
 
 .. toctree::
    :maxdepth: 2
+   :glob:
 
-   api/fixtures
+   api/*
-   api/formatters
-   api/handlers
-   api/helpers
-   api/log
 
 Indices and tables
 ==================

doc/source/usage.rst

@@ -71,15 +71,10 @@ Deprecation tools moved to ``versionutils``
 -------------------------------------------
 
 The :meth:`deprecated` decorator and :class:`DeprecatedConfig` have
-moved to the :mod:`versionutils` module, which is still in the
+moved to :mod:`oslo_log.versionutils`.  Replace ``LOG.deprecated()``
-oslo-incubator repository. Updating to use oslo.log may require
+with :mod:`oslo_log.versionutils.report_deprecated_feature`, passing a
-syncing a new version of :mod:`versionutils` at the same time, and
+local logger object as the first argument so the log message includes
-updating existing uses of those symbols.
+the location information.
-
-Replace ``LOG.deprecated()`` with
-``versionutils.report_deprecated_feature()``, passing a local logger
-object as the first argument so the log message includes the location
-information.
 
 No more implicit conversion to unicode/str
 ------------------------------------------

oslo_log/versionutils.py

@@ -75,10 +75,12 @@ class deprecated(object):
     ... def c(): pass
 
     4. Specifying the deprecated functionality will not be removed:
+
     >>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=0)
     ... def d(): pass
 
     5. Specifying a replacement, deprecated functionality will not be removed:
+
     >>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()', remove_in=0)
     ... def e(): pass