doc migration

- fix sphinx errors
- enable warning-is-error
- reorganize structure
- use openstackdocstheme

Change-Id: I87df64b3a57e03618072a53bbe66bd3e83ac4e72

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

doc/source/contributor/index.rst

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

doc/source/index.rst

@@ -9,16 +9,21 @@ Welcome to python-congressclient's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   readme
+   user/readme
-   installation
+   install/index
-   usage
+   user/index
-   contributing
+   contributor/index
-
+   reference/index
-Indices and tables
-==================
 
 * :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

doc/source/readme.rst

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

doc/source/reference/index.rst

@@ -0,0 +1,5 @@
+==========
+References
+==========
+
+* :ref:`modindex`

doc/source/user/index.rst

@@ -1,6 +1,6 @@
-========
+=====
 Usage
-========
+=====
 
 To use python-congressclient in a project::
 

doc/source/user/readme.rst

@@ -0,0 +1,5 @@
+##########
+README
+##########
+
+.. include:: ../../../README.rst

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