.. _logging-api:

Logging API

.. currentmodule:: sphinx.util.logging

.. autofunction:: getLogger(name)

.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)

.. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.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 :confval:`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"``.

.. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.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
    :meth:`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"``.

.. autofunction:: pending_logging()

.. autofunction:: pending_warnings()

.. autofunction:: prefixed_warnings()