Logging API
***********

sphinx.util.logging.getLogger(name)

   Get logger wrapped by "sphinx.util.logging.SphinxLoggerAdapter".

   Sphinx logger always uses "sphinx.*" namespace to be independent
   from settings of root logger.  It ensures logging is consistent
   even if a third-party extension or imported application resets
   logger settings.

   Example usage:

      >>> from sphinx.util import logging
      >>> logger = logging.getLogger(__name__)
      >>> logger.info('Hello, this is an extension!')
      Hello, this is an extension!

class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)

   LoggerAdapter allowing "type" and "subtype" keywords.

   error(msg, *args, **kwargs)

   critical(msg, *args, **kwargs)

   warning(msg, *args, **kwargs)

      Logs a message on this logger with the specified level.
      Basically, the arguments are as with python's logging module.

      In addition, Sphinx logger supports following keyword arguments:

      **type**, ***subtype***
         Categories of warning logs.  It is used to suppress warnings
         by "suppress_warnings" setting.

      **location**
         Where the warning happened.  It is used to include the path
         and line number in 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**
         The color of logs.  By default, error level logs are colored
         as ""darkred"", critical level ones is not colored, and
         warning level ones are colored as ""red"".

   log(level, msg, *args, **kwargs)

   info(msg, *args, **kwargs)

   verbose(msg, *args, **kwargs)

   debug(msg, *args, **kwargs)

      Logs a message to this logger with the specified level.
      Basically, the arguments are as with python's logging module.

      In addition, Sphinx logger supports following keyword arguments:

      **nonl**
         If true, the logger does not fold lines at the end of the log
         message. The default is "False".

      **location**
         Where the message emitted.  For more detail, see
         "SphinxLoggerAdapter.warning()".

      **color**
         The color of logs.  By default, info and verbose level logs
         are not colored, and debug level ones are colored as
         ""darkgray"".

sphinx.util.logging.pending_logging()

   Context manager to postpone logging all logs temporarily.

   For example:

      >>> with pending_logging():
      >>>     logger.warning('Warning message!')  # not flushed yet
      >>>     some_long_process()
      >>>
      Warning message!  # the warning is flushed here

sphinx.util.logging.pending_warnings()

   Context manager to postpone logging warnings temporarily.

   Similar to "pending_logging()".

sphinx.util.logging.prefixed_warnings()

   Context manager to prepend prefix to all warning log records
   temporarily.

   For example:

      >>> with prefixed_warnings("prefix:"):
      >>>     logger.warning('Warning message!')  # => prefix: Warning message!

   New in version 2.0.
