Add API documentation

Add basic API documentation for the public parts of the libary.

Change-Id: Ie3df3c6a1517c2d1b9f9fc052528c62b8fdde388

doc/source/api/formatters.rst

@@ -0,0 +1,8 @@
+=====================
+ oslo_log.formatters
+=====================
+
+.. automodule:: oslo_log.formatters
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/handlers.rst

@@ -0,0 +1,8 @@
+=====================
+ oslo_log.handlers
+=====================
+
+.. automodule:: oslo_log.handlers
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/helpers.rst

@@ -0,0 +1,8 @@
+==================
+ oslo_log.helpers
+==================
+
+.. automodule:: oslo_log.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/index.rst

@@ -0,0 +1,9 @@
+===============
+ API Reference
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

doc/source/api/log.rst

@@ -0,0 +1,12 @@
+==============
+ oslo_log.log
+==============
+
+.. automodule:: oslo_log.log
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. seealso::
+
+   :doc:`../usage`

doc/source/index.rst

@@ -11,6 +11,7 @@ Contents
    :maxdepth: 2
 
    installation
+   api/index
    usage
    contributing
    history

doc/source/usage.rst

@@ -2,6 +2,29 @@
  Usage
 =======
 
-To use oslo.log in a project::
+In a Library
+============
 
-    import oslo_log
+oslo.log is primarily used for configuring logging in an application,
+but it does include helpers that can be useful from libraries.
+
+:func:`~oslo_log.log.getLogger` wraps the function of the same name
+from Python's standard library to add a
+:class:`~oslo_log.log.KeywordArgumentAdapter`, making it easier to
+pass data to the formatters provided by oslo.log and configured by an
+application.
+
+In an Application
+=================
+
+Applications should use oslo.log's configuration functions to register
+logging-related configuration options and configure the root and other
+default loggers.
+
+Call :func:`~oslo_log.log.register_options` before parsing command
+line options.
+
+Call :func:`~oslo_log.log.set_defaults` before configuring logging.
+
+Call :func:`~oslo_log.log.setup` to configure logging for the
+application.

oslo_log/log.py

@@ -148,6 +148,7 @@ def _load_log_config(log_config_append):
 
 
 def register_options(conf):
+    """Register the command line and configuration options used by oslo.log."""
     conf.register_cli_opts(_options.common_cli_opts)
     conf.register_cli_opts(_options.logging_cli_opts)
     conf.register_opts(_options.generic_log_opts)
@@ -156,7 +157,7 @@ def register_options(conf):
 
 
 def setup(conf, product_name, version='unknown'):
-    """Setup logging."""
+    """Setup logging for the current application."""
     if conf.log_config_append:
         _load_log_config(conf.log_config_append)
     else:
@@ -166,6 +167,7 @@ def setup(conf, product_name, version='unknown'):
 
 def set_defaults(logging_context_format_string=None,
                  default_log_levels=None):
+    """Set default values for the configuration options used by oslo.log."""
     # Just in case the caller is not setting the
     # default_log_level. This is insurance because
     # we introduced the default_log_level parameter