Add API docs and clean up other docs

Add auto-generated documentation for the public modules in the library
and clean up a bit of the docstrings used.

Change-Id: Id5efa5c413b82e13f1a7ac78c92e39c193f12214

CONTRIBUTING.rst

@@ -14,4 +14,4 @@ Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
 
-   https://bugs.launchpad.net/oslo.utils
+   https://bugs.launchpad.net/oslo

doc/source/api/encodeutils.rst

@@ -0,0 +1,6 @@
+=============
+ encodeutils
+=============
+
+.. automodule:: oslo.utils.encodeutils
+   :members:

doc/source/api/excutils.rst

@@ -0,0 +1,6 @@
+==========
+ excutils
+==========
+
+.. automodule:: oslo.utils.excutils
+   :members:

doc/source/api/importutils.rst

@@ -0,0 +1,6 @@
+=============
+ importutils
+=============
+
+.. automodule:: oslo.utils.importutils
+   :members:

doc/source/api/index.rst

@@ -0,0 +1,9 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

doc/source/api/netutils.rst

@@ -0,0 +1,6 @@
+==========
+ netutils
+==========
+
+.. automodule:: oslo.utils.netutils
+   :members:

doc/source/api/strutils.rst

@@ -0,0 +1,6 @@
+==========
+ strutils
+==========
+
+.. automodule:: oslo.utils.strutils
+   :members:

doc/source/api/timeutils.rst

@@ -0,0 +1,6 @@
+===========
+ timeutils
+===========
+
+.. automodule:: oslo.utils.timeutils
+   :members:

doc/source/api/units.rst

@@ -0,0 +1,6 @@
+=======
+ units
+=======
+
+.. automodule:: oslo.utils.units
+   :members:

doc/source/contributing.rst

@@ -1 +1,5 @@
-.. include:: ../../CONTRIBUTING.rst
+==============
+ Contributing
+==============
+
+.. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -9,6 +9,7 @@ Contents:
    readme
    installation
    usage
+   api/index
    contributing
 
 Indices and tables

doc/source/readme.rst

@@ -1 +1 @@
-.. include:: ../README.rst
+.. include:: ../../README.rst

doc/source/usage.rst

@@ -1,7 +1,10 @@
-========
+=========
-Usage
+ Usage
-========
+=========
 
-To use oslo.utils in a project::
+To use oslo.utils in a project, import the individual module you
+need. For example::
 
-	import oslo.utils
+	from oslo.utils import strutils
+
+    slug = strutils.to_slug('input value')

oslo/utils/netutils.py

@@ -95,7 +95,9 @@ class ModifiedSplitResult(parse.SplitResult):
 
 def urlsplit(url, scheme='', allow_fragments=True):
     """Parse a URL using urlparse.urlsplit(), splitting query and fragments.
-    This function papers over Python issue9374 when needed.
+    This function papers over Python issue9374_ when needed.
+
+    .. _issue9374: http://bugs.python.org/issue9374
 
     The parameters are the same as urlparse.urlsplit.
     """

setup.cfg

@@ -25,6 +25,9 @@ packages =
 namespace_packages =
     oslo
 
+[pbr]
+warnerrors = true
+
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build

tox.ini

@@ -22,6 +22,9 @@ commands = flake8
 [testenv:venv]
 commands = {posargs}
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:cover]
 commands = python setup.py testr --coverage --testr-args='{posargs}'