Docs for logging

Change-Id: I694e02b1607ecc2602b64a89a483aa70e864a8a0
Closes-Bug: 1420060

doc/source/conf.py

@@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
+    'sphinx.ext.intersphinx',
     'oslosphinx',
 ]
 
@@ -77,7 +77,7 @@ latex_documents = [
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'http://docs.python.org/3/': None}
 
 # Include both the class and __init__ docstrings when describing the class
 autoclass_content = "both"

doc/source/users/index.rst

@@ -24,6 +24,7 @@ approach, this is where you'll want to begin.
    :maxdepth: 1
 
    Connecting to an OpenStack Cloud <userguides/usage>
+   Logging <userguides/logging>
    Block Store <userguides/block_store>
    CDN <userguides/cdn>
    Compute <userguides/compute>

doc/source/users/userguides/logging.rst

@@ -0,0 +1,79 @@
+Logging
+=======
+
+Logging can save you time and effort when developing your code or looking
+for help. If your code is not behaving how you expect it to, enabling and
+configuring logging can quickly give you valuable insight into the root
+cause of the issue. If you need help from the OpenStack community, the
+logs can help the people there assist you.
+
+.. note:: By default, no logging is done.
+
+Enable SDK Logging
+------------------
+
+To enable logging you use :func:`~openstack.utils.enable_logging`.
+
+The ``debug`` parameter controls the logging level. Set ``debug=True`` to
+log debug and higher messages. Set ``debug=False`` to log warning and higher
+messages.
+
+To log debug and higher messages::
+
+    import sys
+    from openstack import utils
+
+    utils.enable_logging(debug=True, stream=sys.stdout)
+
+The ``path`` parameter controls the location of a log file. If set, this
+parameter will send log messages to a file using a :py:class:`~logging.FileHandler`.
+
+To log messages to a file called ``openstack.log``::
+
+    from openstack import utils
+
+    utils.enable_logging(debug=True, path='openstack.log')
+
+The ``stream`` parameter controls the stream where log message are written to.
+If set to ``sys.stdout`` or ``sys.stderr``, this parameter will send log
+messages to that stream using a :py:class:`~logging.StreamHandler`
+
+To log messages to the console on ``stdout``::
+
+    import sys
+    from openstack import utils
+
+    utils.enable_logging(debug=True, stream=sys.stdout)
+
+You can combine the ``path`` and ``stream`` parameters to log to both places
+simultaneously.
+
+To log messages to a file called ``openstack.log`` and the console on
+``stdout``::
+
+    import sys
+    from openstack import utils
+
+    utils.enable_logging(debug=True, path='openstack.log', stream=sys.stdout)
+
+
+Enable requests Logging
+-----------------------
+
+The SDK depends on a small number other libraries. Notably, it uses
+`requests <https://pypi.python.org/pypi/requests>`_ for its transport layer.
+To get even more information about the request/response cycle, you enable
+logging of requests the same as you would any other library.
+
+To log messages to the console on ``stdout``::
+
+    import logging
+    import sys
+
+    logger = logging.getLogger('requests')
+    formatter = logging.Formatter(
+        '%(asctime)s %(levelname)s: %(name)s %(message)s')
+    console = logging.StreamHandler(sys.stdout)
+    console.setFormatter(formatter)
+    logger.setLevel(logging.DEBUG)
+    logger.addHandler(console)