Update docs for first release

Ensure each exported class has a docstring.

Add API to the sphinx docs.

Fix a few formatting issues so the rendered docs look OK.

Change-Id: Ieef7bae3783a084249169fe9b80ab17518eee15f

10 files changed, 31 insertions, 36 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 2440ec0..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.middleware
\ No newline at end of file
+   https://bugs.launchpad.net/oslo
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 0000000..db58162
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,6 @@
+=====
+ API
+=====
+
+.. automodule:: oslo.middleware
+   :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 8aae142..390cea6 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,19 +1,11 @@
-Welcome to oslo.middleware's documentation!
-===========================================
+.. include:: ../../README.rst
 
-Contents:
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   usage
+   api
    contributing
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 6b2b3ec..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/usage.rst b/doc/source/usage.rst
deleted file mode 100644
index 589e40f..0000000
--- a/doc/source/usage.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use oslo.middleware in a project::
-
-	import oslo.middleware
\ No newline at end of file
diff --git a/oslo/middleware/catch_errors.py b/oslo/middleware/catch_errors.py
index 73aeb9e..ed57f8a 100644
--- a/oslo/middleware/catch_errors.py
+++ b/oslo/middleware/catch_errors.py
@@ -13,11 +13,6 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Middleware that provides high-level error handling.
-
-It catches all exceptions from subsequent applications in WSGI pipeline
-to hide internal errors from API response.
-"""
 import logging
 
 import webob.dec
@@ -31,6 +26,11 @@ LOG = logging.getLogger(__name__)
 
 
 class CatchErrors(base.Middleware):
+    """Middleware that provides high-level error handling.
+
+    It catches all exceptions from subsequent applications in WSGI pipeline
+    to hide internal errors from API response.
+    """
 
     @webob.dec.wsgify
     def __call__(self, req):
diff --git a/oslo/middleware/correlation_id.py b/oslo/middleware/correlation_id.py
index 3923654..2cde134 100644
--- a/oslo/middleware/correlation_id.py
+++ b/oslo/middleware/correlation_id.py
@@ -13,14 +13,13 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Middleware that attaches a correlation id to WSGI request"""
-
 import uuid
 
 from oslo.middleware import base
 
 
 class CorrelationId(base.Middleware):
+    "Middleware that attaches a correlation id to WSGI request"
 
     def process_request(self, req):
         correlation_id = (req.headers.get("X_CORRELATION_ID") or
diff --git a/oslo/middleware/request_id.py b/oslo/middleware/request_id.py
index 4d356b5..f3a22c1 100644
--- a/oslo/middleware/request_id.py
+++ b/oslo/middleware/request_id.py
@@ -13,12 +13,6 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Middleware that ensures request ID.
-
-It ensures to assign request ID for each API request and set it to
-request environment. The request ID is also added to API response.
-"""
-
 import webob.dec
 
 from oslo.middleware import base
@@ -30,6 +24,11 @@ HTTP_RESP_HEADER_REQUEST_ID = 'x-openstack-request-id'
 
 
 class RequestId(base.Middleware):
+    """Middleware that ensures request ID.
+
+    It ensures to assign request ID for each API request and set it to
+    request environment. The request ID is also added to API response.
+    """
 
     @webob.dec.wsgify
     def __call__(self, req):
diff --git a/setup.cfg b/setup.cfg
index 2a24ca6..4267183 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -45,4 +45,7 @@ input_file = oslo.middleware/locale/oslo.middleware.pot
 [extract_messages]
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
-output_file = oslo.middleware/locale/oslo.middleware.pot
\ No newline at end of file
+output_file = oslo.middleware/locale/oslo.middleware.pot
+
+[pbr]
+warnerrors = True
\ No newline at end of file