From 8140ae33b51b17089f189ada27d280d79837c43b Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Wed, 28 Dec 2016 21:14:56 +0900
Subject: [PATCH] Add doc/extdev/logging.rst

---
 doc/extdev/index.rst   |  1 +
 doc/extdev/logging.rst | 78 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 doc/extdev/logging.rst

diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index b27db4b2d..1f3871c21 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -54,3 +54,4 @@ APIs used for writing extensions
    domainapi
    parserapi
    nodes
+   logging
diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst
new file mode 100644
index 000000000..169bf6a5a
--- /dev/null
+++ b/doc/extdev/logging.rst
@@ -0,0 +1,78 @@
+.. _logging-api:
+
+Logging API
+===========
+
+.. function:: sphinx.util.logging.getLogger(name)
+
+   Return a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*.
+
+   Example usage::
+
+     from sphinx.util import logging  # Load instead python's logging module
+
+     logger = logging.getLogger(__name__)
+     logger.info('Hello, this is an extension!')
+
+.. class:: SphinxLoggerAdapter(logging.LoggerAdapter)
+
+   .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.warning(level, msg, *args, **kwargs)
+
+      Logs a message with specified level on this logger.
+      Basically, the arguments are same as python's logging module.
+
+      In addition, Sphinx logger supports following keyword arguments:
+
+      **type**, ***subtype***
+        Indicate categories of warning logs.  It is used to suppress
+        warnings by :confval:`suppress_warnings` setting.
+
+      **location**
+        Indicate where the warning is happened.  It is used to show
+        the path and line number to each log.  It allows docname,
+        tuple of docname and line number and nodes::
+
+          logger = sphinx.util.logging.getLogger(__name__)
+          logger.warning('Warning happened!', location='index')
+          logger.warning('Warning happened!', location=('chapter1/index', 10))
+          logger.warning('Warning happened!', location=some_node)
+
+      **color**
+        Indicate the color of logs.  By default, warning level logs are
+        colored as ``"darkred"``.  The others are not colored.
+
+   .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.info(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.verbose(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.debug2(level, msg, *args, **kwargs)
+
+      Logs a message with specified level on this logger.
+      Basically, the arguments are same as python's logging module.
+
+      In addition, Sphinx logger supports following keyword arguments:
+
+      **nonl**
+        If true, the logger does not fold lines at end of the log message.
+        The default is ``False``.
+
+      **color**
+        Indicate the color of logs.  By default, debug level logs are
+        colored as ``"darkgray"``, and debug2 ones are ``"lightgray"``.
+        The others are not colored.
+
+.. function:: pending_logging()
+
+   Make all logs as pending while the context::
+
+     with pending_logging():
+       logger.warning('Warning message!')  # not flushed yet
+       some_long_process()
+
+     # the warning is flushed here
+
+.. function:: pending_warnings()
+
+   Make warning logs as pending while the context.  Similar to :func:`pending_logging`.