sphinx/doc/extdev/logging.rst

.. _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 deug level ones are colored as ``"darkgray"``.

.. autofunction:: pending_logging()

.. autofunction:: pending_warnings()