Use extras for oslo.messaging dependency

Install the oslo.messaging optional dependency by doing:

  keystonemiddleware[audit_notifications]

pbr documentation:

  http://docs.openstack.org/developer/pbr/#environment-markers

Partial-Bug: 1540115

Change-Id: I59eea1f7eb0e770ac4fe30211eff49ae76fb2550

doc/source/index.rst

@@ -13,6 +13,7 @@ Contents:
 
    middlewarearchitecture
    audit
+   installation
 
 Related Identity Projects
 =========================

doc/source/installation.rst

@@ -0,0 +1,25 @@
+==============
+ Installation
+==============
+
+Install using pip
+-----------------
+
+At the command line::
+
+    $ pip install keystonemiddleware
+
+Or, if you want to use it in a virtualenvwrapper::
+
+    $ mkvirtualenv keystonemiddleware
+    $ pip install keystonemiddleware
+
+Install optional dependencies
+-----------------------------
+
+Certain keystonemiddleware features are only available if specific libraries
+are available. These libraries can be installed using pip as well.
+
+To install support for audit notifications::
+
+    $ pip install keystonemiddleware[audit_notifications]

releasenotes/notes/bug_1540115-677cf5016bc46348.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - >
+    [`bug 1540115 <https://bugs.launchpad.net/keystonemiddleware/+bug/1540115>`_]
+    Optional dependencies can now be installed using `extras`. To install audit
+    related libraries, use ``pip install keystonemiddleware[audit_nofications]``.
+    Refer to keystonemiddleware documentation for further information.

setup.cfg

@@ -22,6 +22,10 @@ classifier =
 packages =
     keystonemiddleware
 
+[extras]
+audit_notifications =
+  oslo.messaging>=5.2.0 # Apache-2.0
+
 [global]
 setup-hooks =
     pbr.hooks.setup_hook

test-requirements.txt

@@ -11,7 +11,6 @@ mock>=2.0 # BSD
 pycrypto>=2.6 # Public Domain
 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
-oslo.messaging>=5.2.0 # Apache-2.0
 reno>=1.8.0 # Apache2
 requests-mock>=1.0 # Apache-2.0
 sphinx!=1.3b1,<1.3,>=1.2.1 # BSD
@@ -23,4 +22,3 @@ python-memcached>=1.56 # PSF
 
 # Bandit security code scanner
 bandit>=1.0.1 # Apache-2.0
-

tox.ini

@@ -12,6 +12,7 @@ setenv = VIRTUAL_ENV={envdir}
 
 deps = -r{toxinidir}/requirements.txt
        -r{toxinidir}/test-requirements.txt
+       .[audit_notifications]
 commands = python setup.py testr --testr-args='{posargs}'
 
 [testenv:pep8]