From 3a5fc4bcb83546141b37f02ec49ee6470452c08e Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Tue, 8 Jan 2013 11:18:42 +0000 Subject: [PATCH] Issue #16884: Updated docs to use 'note' directives. --- Doc/howto/logging.rst | 23 ++++++++++++----------- Doc/library/logging.rst | 32 ++++++++++++++++---------------- 2 files changed, 28 insertions(+), 27 deletions(-) diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index 79e4dc98765..666e08a7b3b 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -757,13 +757,14 @@ should have the desired effect. If an organisation produces a number of libraries, then the logger name specified can be 'orgname.foo' rather than just 'foo'. -**PLEASE NOTE:** It is strongly advised that you *do not add any handlers other -than* :class:`~logging.NullHandler` *to your library's loggers*. This is -because the configuration of handlers is the prerogative of the application -developer who uses your library. The application developer knows their target -audience and what handlers are most appropriate for their application: if you -add handlers 'under the hood', you might well interfere with their ability to -carry out unit tests and deliver logs which suit their requirements. +.. note:: It is strongly advised that you *do not add any handlers other + than* :class:`~logging.NullHandler` *to your library's loggers*. This is + because the configuration of handlers is the prerogative of the application + developer who uses your library. The application developer knows their + target audience and what handlers are most appropriate for their + application: if you add handlers 'under the hood', you might well interfere + with their ability to carry out unit tests and deliver logs which suit their + requirements. Logging Levels @@ -940,10 +941,10 @@ The default implementation of :meth:`handleError` in :class:`Handler` checks to see if a module-level variable, :data:`raiseExceptions`, is set. If set, a traceback is printed to :data:`sys.stderr`. If not set, the exception is swallowed. -**Note:** The default value of :data:`raiseExceptions` is ``True``. This is because -during development, you typically want to be notified of any exceptions that -occur. It's advised that you set :data:`raiseExceptions` to ``False`` for production -usage. +.. note:: The default value of :data:`raiseExceptions` is ``True``. This is + because during development, you typically want to be notified of any + exceptions that occur. It's advised that you set :data:`raiseExceptions` to + ``False`` for production usage. .. currentmodule:: logging diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 7ed1f1ab13f..67e51bd9d6a 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -800,14 +800,14 @@ functions. Logs a message with level *level* on the root logger. The other arguments are interpreted as for :func:`debug`. - PLEASE NOTE: The above module-level functions which delegate to the root - logger should *not* be used in threads, in versions of Python earlier than - 2.7.1 and 3.2, unless at least one handler has been added to the root - logger *before* the threads are started. These convenience functions call - :func:`basicConfig` to ensure that at least one handler is available; in - earlier versions of Python, this can (under rare circumstances) lead to - handlers being added multiple times to the root logger, which can in turn - lead to multiple messages for the same event. + .. note:: The above module-level functions which delegate to the root + logger should *not* be used in threads, in versions of Python earlier + than 2.7.1 and 3.2, unless at least one handler has been added to the + root logger *before* the threads are started. These convenience functions + call :func:`basicConfig` to ensure that at least one handler is + available; in earlier versions of Python, this can (under rare + circumstances) lead to handlers being added multiple times to the root + logger, which can in turn lead to multiple messages for the same event. .. function:: disable(lvl) @@ -830,8 +830,8 @@ functions. registered using this function, levels should be positive integers and they should increase in increasing order of severity. - NOTE: If you are thinking of defining your own levels, please see the section - on :ref:`custom-levels`. + .. note:: If you are thinking of defining your own levels, please see the + section on :ref:`custom-levels`. .. function:: getLevelName(lvl) @@ -866,12 +866,12 @@ functions. .. versionchanged:: 2.4 Formerly, :func:`basicConfig` did not take any keyword arguments. - PLEASE NOTE: This function should be called from the main thread - before other threads are started. In versions of Python prior to - 2.7.1 and 3.2, if this function is called from multiple threads, - it is possible (in rare circumstances) that a handler will be added - to the root logger more than once, leading to unexpected results - such as messages being duplicated in the log. + .. note:: This function should be called from the main thread before other + threads are started. In versions of Python prior to 2.7.1 and 3.2, if + this function is called from multiple threads, it is possible (in rare + circumstances) that a handler will be added to the root logger more than + once, leading to unexpected results such as messages being duplicated in + the log. The following keyword arguments are supported.