Declare an extras directory for plugins

Create an extras directory and add some explanatory documentation for
dealing with plugins defined in extras.

Change-Id: Ibdd6bc16f38d1b9ca38db775671876458ec60e7a

doc/source/extras.rst

@@ -0,0 +1,24 @@
+======
+Extras
+======
+
+The extensibility of keystoneauth plugins is purposefully designed to allow a
+range of different authentication mechanisms that don't have to reside in the
+upstream packages. There are however a number of plugins that upstream supports
+that involve additional dependencies that the keystoneauth package cannot
+depend upon directly.
+
+To get around this we utilize setuptools `extras dependencies <https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_ for additional
+plugins. To use a plugin like the kerberos plugin that has additional
+dependencies you must install the additional dependencies like::
+
+    pip install keystoneauth1[kerberos]
+
+By convention (not a requirement) extra plugins have a module located in the
+keystoneauth1.extras module with the same name as the dependency. eg::
+
+    $ from keystoneauth1.extras import kerberos
+
+There is no keystoneauth specific check that the correct dependencies are
+installed for accessing a module. You would expect to see standard python
+ImportError when the required dependencies are not found.

doc/source/index.rst

@@ -13,6 +13,9 @@ Contents:
 
    using-sessions
    authentication-plugins
+
+   extras
+
    api/modules
 
 Release Notes

keystoneauth1/extras/__init__.py

@@ -0,0 +1,20 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+# NOTE(jamielennox): This directory is designed to reflect the dependency
+# extras in the setup.cfg file. If you create an additional dependency section
+# like 'kerberos' in the setup.cfg it is expected that there be a kerberos
+# package here that can be imported.
+#
+# e.g. from keystoneauth1.extras import kerberos
+
+pass