diff --git a/congressclient/v1/client.py b/congressclient/v1/client.py
index 1d428d4..14bdc57 100644
--- a/congressclient/v1/client.py
+++ b/congressclient/v1/client.py
@@ -18,7 +18,9 @@ from keystoneauth1 import adapter
 class Client(object):
     """Client for the Congress v1 API.
 
-    Example::
+    Example
+    ::
+
         from keystoneauth1.identity import v2
         from keystoneauth1 import session
         from congressclient.v1 import client
diff --git a/doc/source/contributing.rst b/doc/source/contributor/index.rst
similarity index 50%
rename from doc/source/contributing.rst
rename to doc/source/contributor/index.rst
index ed77c12..5da9f94 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributor/index.rst
@@ -1,4 +1,4 @@
 ============
 Contributing
 ============
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+.. include:: ../../../CONTRIBUTING.rst
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 42d230c..58d8047 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,16 +9,21 @@ Welcome to python-congressclient's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   readme
-   installation
-   usage
-   contributing
-
-Indices and tables
-==================
+   user/readme
+   install/index
+   user/index
+   contributor/index
+   reference/index
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
+
+.. # Below are items we don't want to show doc consumers but need to be
+   # included to avoid sphinx warning/error.
+   # api/autoindex hidden because the information is already in modindex above
+.. toctree::
+   :hidden:
+
+   reference/api/autoindex
\ No newline at end of file
diff --git a/doc/source/installation.rst b/doc/source/install/index.rst
similarity index 100%
rename from doc/source/installation.rst
rename to doc/source/install/index.rst
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 38ba804..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
\ No newline at end of file
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..10119c9
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,5 @@
+==========
+References
+==========
+
+* :ref:`modindex`
\ No newline at end of file
diff --git a/doc/source/usage.rst b/doc/source/user/index.rst
similarity index 56%
rename from doc/source/usage.rst
rename to doc/source/user/index.rst
index 79aac94..797ce54 100644
--- a/doc/source/usage.rst
+++ b/doc/source/user/index.rst
@@ -1,6 +1,6 @@
-========
+=====
 Usage
-========
+=====
 
 To use python-congressclient in a project::
 
diff --git a/doc/source/user/readme.rst b/doc/source/user/readme.rst
new file mode 100644
index 0000000..8b7ba60
--- /dev/null
+++ b/doc/source/user/readme.rst
@@ -0,0 +1,5 @@
+##########
+README
+##########
+
+.. include:: ../../../README.rst
diff --git a/setup.cfg b/setup.cfg
index 6d8eff6..4e9d140 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -58,12 +58,14 @@ openstack.congressclient.v1 =
 
 [pbr]
 autodoc_index_modules = True
+api_doc_dir = reference/api
 warnerrors = True
 
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build
 all_files = 1
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html