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

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
+   https://bugs.launchpad.net/oslo

doc/source/api.rst

@@ -0,0 +1,6 @@
+=====
+ API
+=====
+
+.. automodule:: oslo.middleware
+   :members:

doc/source/contributing.rst

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

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`

doc/source/readme.rst

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

doc/source/usage.rst

@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use oslo.middleware in a project::
-
-	import oslo.middleware

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):

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

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):

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
+output_file = oslo.middleware/locale/oslo.middleware.pot
+
+[pbr]
+warnerrors = True