cleanup documentation

- fix image width to conform to formatting
- move specification out of dev section
- redirect middleware doc to keystonemiddleware
- add full spec pdf link to specifications page
- drop tree depth so we don't have 'serialisation' subheaders in toc

Change-Id: Ia36c029b792f574b2b30623b3b2696242b79d75c

4 files changed, 16 insertions, 91 deletions

diff --git a/doc/source/event_concept.rst b/doc/source/event_concept.rst
index 913f174..b2569a9 100644
--- a/doc/source/event_concept.rst
+++ b/doc/source/event_concept.rst
@@ -33,7 +33,7 @@ perspective of a single RESOURCE called the OBSERVER that is responsible for
 observing the Actual Event and creating the (initial) CADF Event Record.
 
 .. figure:: ./images/observer_cadf.png
-   :figwidth: 100%
+   :width: 100%
    :align: center
    :alt: Figure 1: Observer perspective of an Event
 
@@ -62,7 +62,7 @@ activities including "logon" attempts against any servers within the
 provider's infrastructure.
 
 .. figure:: ./images/audit_event.png
-   :figwidth: 100%
+   :width: 100%
    :align: center
    :alt: Figure 2: Conceptually mapping values of an audit event
 
@@ -128,7 +128,7 @@ status of each server's CPU utilisation along with metric data to their
 operations management software by using the CADF Event Record format.
 
 .. figure:: ./images/monitor_event.png
-   :figwidth: 100%
+   :width: 100%
    :align: center
    :alt: Figure 3: Conceptually mapping values of an monitor event
 
@@ -172,4 +172,4 @@ Event serialisation::
 
 .. note::
 
-   Additional use cases can be found in the Full CADF specification.
\ No newline at end of file
+   Additional use cases can be found in the Full CADF specification.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e930d46..5f2ba36 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -42,6 +42,7 @@ Getting Started
     :maxdepth: 1
 
     event_concept
+    specification/index
     middleware
 
 Developer Documentation
@@ -52,7 +53,6 @@ Developer Documentation
 
     contributing
     debugging
-    specification/index
 
 Code Documentation
 ==================
diff --git a/doc/source/middleware.rst b/doc/source/middleware.rst
index 22d7410..fe8f748 100644
--- a/doc/source/middleware.rst
+++ b/doc/source/middleware.rst
@@ -19,85 +19,8 @@
  Audit middleware
 =================
 
-The pyCADF library provides an optional WSGI middleware filter which allows
-the ability to audit api requests for each component of OpenStack.
+pyCADF's version of the audit middleware has been deprecated as of pyCADF
+0.8.0. For continued support, the middleware is now maintained under the
+Identity (Keystone) umbrella. Related documentation can be found here_.
 
-The audit middleware filter utilises environment variables to build the CADF
-event.
-
-.. figure:: ./images/middleware.png
-   :figwidth: 100%
-   :align: center
-   :alt: Figure 1: Audit middleware in Nova pipeline
-
-The figure above shows the middleware in Nova's pipeline.
-
-Enabling audit middleware
-=========================
-To enable the audit middleware, the following requirements need to be
-satisfied:
-
-1. pyCADF library must be added to the requirements file of the project to be
-   audited.
-
-2. The project should utilise oslo.messaging_ notification system.
-
-.. note::
-
-   If the project utilises oslo's `old notification system`_, a compatible
-   middleware can be synced from oslo-incubator's `middleware code base`_.
-
-If the above requirements are satisfied, auditing can be enabled by editing
-the project's api-paste.ini file to include the following filter definition:
-
-::
-
-   [filter:audit]
-   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
-
-or
-
-::
-
-   [filter:audit]
-   paste.filter_factory = <project>.openstack.common.middleware.audit:AuditMiddleware.factory
-
-The filter should be included after Keystone's auth_token middleware so it can
-utilise environment variables set by Keystone's middleware.  Below is an
-example using Nova's WSGI pipeline::
-
-   [composite:openstack_compute_api_v2]
-   use = call:nova.api.auth:pipeline_factory
-   noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2
-   keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2
-   keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2
-
-.. _oslo.messaging: https://github.com/openstack/oslo.messaging
-.. _old notification system: https://github.com/openstack/oslo-incubator
-.. _middleware code base: https://github.com/openstack/oslo-incubator/tree/master/openstack/common/middleware
-
-Configure audit middleware
-==========================
-To properly audit api requests, the audit middleware requires an
-api_audit_map.conf to be defined. The project's corresponding
-api_audit_map.conf file is included in the `pyCADF library`_.
-
-By default, the audit middleware filter expects the map file to be located in
-the same folder as the other conf files related to the project
-(ie.'/etc/<project>' folder). This default functionality is to be deprecated
-and so the location should be specified explicitly by adding the path to the
-'audit_map_file' option of the filter definition::
-
-   [filter:audit]
-   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
-   audit_map_file = /etc/nova/api_audit_map.conf
-
-Additional options can be set::
-
-   [filter:audit]
-   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
-   audit_map_file = /etc/nova/api_audit_map.conf
-   service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable
-   ignore_req_list = GET,POST # opt to ignore specific requests
-
-.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf
+.. _here: http://docs.openstack.org/developer/keystonemiddleware/audit.html
diff --git a/doc/source/specification/index.rst b/doc/source/specification/index.rst
index 56d2e06..9037bf7 100644
--- a/doc/source/specification/index.rst
+++ b/doc/source/specification/index.rst
@@ -2,14 +2,16 @@
  Specification
 ==============
 
-The following is a high-level description of the CADF specification. The basic
-component of the CADF spec are Events. The full CADF specification document
-can be found here_.
+The following is a high-level description of components in the CADF
+specification. The basic component of the CADF specification are Events. The
+full CADF specification document can be found here_. Additional details on the
+CADF specification are accessible via the `DMTF CADF`_ page.
 
-.. _here: http://www.dmtf.org/standards/cadf
+.. _here: http://dmtf.org/sites/default/files/standards/documents/DSP0262_1.0.0.pdf
+.. _DMTF CADF: http://www.dmtf.org/standards/cadf
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    events
    attachments