IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

doc: Move sphinx.logging API docs to code

Browse Source 
Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2017-12-04 20:30:48 +00:00
parent b7749c6ca3
commit b215f523f7
2 changed files with 29 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/extdev/logging.rst
View File

@ -3,18 +3,11 @@
Logging API
===========
.. function:: sphinx.util.logging.getLogger(name)
.. currentmodule:: sphinx.util.logging
Returns a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*.
.. autofunction:: getLogger(name)
Example usage::
from sphinx.util import logging # Load on top of python's logging module
logger = logging.getLogger(__name__)
logger.info('Hello, this is an extension!')
.. class:: SphinxLoggerAdapter(logging.LoggerAdapter)
.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
.. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
.. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs)
@ -62,16 +55,6 @@ Logging API
colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
The others are not colored.
.. function:: pending_logging()
.. autofunction:: pending_logging()
Marks all logs as pending::
with pending_logging():
logger.warning('Warning message!') # not flushed yet
some_long_process()
# the warning is flushed here
.. function:: pending_warnings()
Marks warning logs as pending. Similar to :func:`pending_logging`.
.. autofunction:: pending_warnings()

29
sphinx/util/logging.py
View File

@ -60,11 +60,18 @@ COLOR_MAP.update({
def getLogger(name):
# type: (str) -> SphinxLoggerAdapter
"""Get logger wrapped by SphinxLoggerAdapter.
"""Get logger wrapped by :class:`sphinx.util.logging.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.
settings of root logger. It ensure logging is consistent even if a
third-party extension or imported application resets logger settings.
Example usage::
>>> from sphinx.utils import logging
>>> logger = logging.getLogger(__name__)
>>> logger.info('Hello, this is an extension!')
Hello, this is an extension!
"""
# add sphinx prefix to name forcely
logger = logging.getLogger(NAMESPACE + '.' + name)
@ -217,7 +224,10 @@ class MemoryHandler(logging.handlers.BufferingHandler):
@contextmanager
def pending_warnings():
# type: () -> Generator
"""contextmanager to pend logging warnings temporary."""
"""Contextmanager to pend logging warnings temporary.
Similar to :func:`pending_logging`.
"""
logger = logging.getLogger(NAMESPACE)
memhandler = MemoryHandler()
memhandler.setLevel(logging.WARNING)
@ -243,7 +253,16 @@ def pending_warnings():
@contextmanager
def pending_logging():
# type: () -> Generator
"""contextmanager to pend logging all logs temporary."""
"""Contextmanager to pend logging all logs temporary.
For example::
>>> with pending_logging():
>>> logger.warning('Warning message!') # not flushed yet
>>> some_long_process()
>>>
Warning message! # the warning is flushed here
"""
logger = logging.getLogger(NAMESPACE)
memhandler = MemoryHandler()