Logging API

sphinx.util.logging.getLogger(name)[fuente]

Get logger wrapped by SphinxLoggerAdapter.

Sphinx logger always uses sphinx.* namesapce to be independent from settings of root logger. It enables to log stably even if 3rd party extension or imported application resets logger settings.

class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)[fuente]

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)[fuente]
info(msg, *args, **kwargs)
verbose(msg, *args, **kwargs)[fuente]
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()[fuente]

contextmanager to pend logging all logs temporary.

sphinx.util.logging.pending_warnings()[fuente]

contextmanager to pend logging warnings temporary.