diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 6d30824..88b16aa 100644
--- a/CONTRIBUTING.rst
+++ b/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
\ No newline at end of file
+   https://bugs.launchpad.net/oslo
diff --git a/doc/source/api/encodeutils.rst b/doc/source/api/encodeutils.rst
new file mode 100644
index 0000000..82ca596
--- /dev/null
+++ b/doc/source/api/encodeutils.rst
@@ -0,0 +1,6 @@
+=============
+ encodeutils
+=============
+
+.. automodule:: oslo.utils.encodeutils
+   :members:
diff --git a/doc/source/api/excutils.rst b/doc/source/api/excutils.rst
new file mode 100644
index 0000000..d39be38
--- /dev/null
+++ b/doc/source/api/excutils.rst
@@ -0,0 +1,6 @@
+==========
+ excutils
+==========
+
+.. automodule:: oslo.utils.excutils
+   :members:
diff --git a/doc/source/api/importutils.rst b/doc/source/api/importutils.rst
new file mode 100644
index 0000000..0864d92
--- /dev/null
+++ b/doc/source/api/importutils.rst
@@ -0,0 +1,6 @@
+=============
+ importutils
+=============
+
+.. automodule:: oslo.utils.importutils
+   :members:
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
new file mode 100644
index 0000000..f193e3b
--- /dev/null
+++ b/doc/source/api/index.rst
@@ -0,0 +1,9 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *
diff --git a/doc/source/api/netutils.rst b/doc/source/api/netutils.rst
new file mode 100644
index 0000000..bb50442
--- /dev/null
+++ b/doc/source/api/netutils.rst
@@ -0,0 +1,6 @@
+==========
+ netutils
+==========
+
+.. automodule:: oslo.utils.netutils
+   :members:
diff --git a/doc/source/api/strutils.rst b/doc/source/api/strutils.rst
new file mode 100644
index 0000000..bd2531b
--- /dev/null
+++ b/doc/source/api/strutils.rst
@@ -0,0 +1,6 @@
+==========
+ strutils
+==========
+
+.. automodule:: oslo.utils.strutils
+   :members:
diff --git a/doc/source/api/timeutils.rst b/doc/source/api/timeutils.rst
new file mode 100644
index 0000000..d1292b3
--- /dev/null
+++ b/doc/source/api/timeutils.rst
@@ -0,0 +1,6 @@
+===========
+ timeutils
+===========
+
+.. automodule:: oslo.utils.timeutils
+   :members:
diff --git a/doc/source/api/units.rst b/doc/source/api/units.rst
new file mode 100644
index 0000000..edd1bed
--- /dev/null
+++ b/doc/source/api/units.rst
@@ -0,0 +1,6 @@
+=======
+ units
+=======
+
+.. automodule:: oslo.utils.units
+   :members:
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 8cb3146..2ca75d1 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1 +1,5 @@
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+==============
+ Contributing
+==============
+
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 211999d..720896a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,6 +9,7 @@ Contents:
    readme
    installation
    usage
+   api/index
    contributing
 
 Indices and tables
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index 6b2b3ec..a6210d3 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1 +1 @@
-.. include:: ../README.rst
\ No newline at end of file
+.. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 35bb227..9e83f6b 100644
--- a/doc/source/usage.rst
+++ b/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
\ No newline at end of file
+	from oslo.utils import strutils
+
+    slug = strutils.to_slug('input value')
diff --git a/oslo/utils/netutils.py b/oslo/utils/netutils.py
index 27b1fab..f9e6beb 100644
--- a/oslo/utils/netutils.py
+++ b/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.
     """
diff --git a/setup.cfg b/setup.cfg
index fb1e954..9aaf088 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -25,6 +25,9 @@ packages =
 namespace_packages =
     oslo
 
+[pbr]
+warnerrors = true
+
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build
diff --git a/tox.ini b/tox.ini
index de8ba05..7a492ff 100644
--- a/tox.ini
+++ b/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}'