Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst
new file mode 100644
index 0000000..e6c4dc6
--- /dev/null
+++ b/doc/extdev/logging.rst
@@ -0,0 +1,66 @@
+.. _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()