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 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:: .. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
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)
.. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs) .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
.. method:: SphinxLoggerAdapter.critical(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"``. colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
The others are not colored. The others are not colored.
.. function:: pending_logging() .. autofunction:: pending_logging()
Marks all logs as pending:: .. autofunction:: pending_warnings()
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`.

29
sphinx/util/logging.py
View File

@ -60,11 +60,18 @@ COLOR_MAP.update({
def getLogger(name): def getLogger(name):
# type: (str) -> SphinxLoggerAdapter # 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 Sphinx logger always uses ``sphinx.*`` namesapce to be independent from
settings of root logger. It enables to log stably even if 3rd party settings of root logger. It ensure logging is consistent even if a
extension or imported application resets logger settings. 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 # add sphinx prefix to name forcely
logger = logging.getLogger(NAMESPACE + '.' + name) logger = logging.getLogger(NAMESPACE + '.' + name)
@ -217,7 +224,10 @@ class MemoryHandler(logging.handlers.BufferingHandler):
@contextmanager @contextmanager
def pending_warnings(): def pending_warnings():
# type: () -> Generator # type: () -> Generator
"""contextmanager to pend logging warnings temporary.""" """Contextmanager to pend logging warnings temporary.
Similar to :func:`pending_logging`.
"""
logger = logging.getLogger(NAMESPACE) logger = logging.getLogger(NAMESPACE)
memhandler = MemoryHandler() memhandler = MemoryHandler()
memhandler.setLevel(logging.WARNING) memhandler.setLevel(logging.WARNING)
@ -243,7 +253,16 @@ def pending_warnings():
@contextmanager @contextmanager
def pending_logging(): def pending_logging():
# type: () -> Generator # 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) logger = logging.getLogger(NAMESPACE)
memhandler = MemoryHandler() memhandler = MemoryHandler()