mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
67 lines
2.3 KiB
ReStructuredText
67 lines
2.3 KiB
ReStructuredText
.. _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()
|