gh-101100: Fix sphinx warnings in `howto/logging.rst` (#114846)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index f164b461c93b9cd1bf82835e42fc57a512a278c3..347330e98dd00c9865361e7bf781924337179e3f 100644 (file)
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -520,7 +520,7 @@ custom handlers) are the following configuration methods:
 
 * The :meth:`~Handler.setLevel` method, just as in logger objects, specifies the
   lowest severity that will be dispatched to the appropriate destination.  Why
-  are there two :func:`setLevel` methods?  The level set in the logger
+  are there two :meth:`~Handler.setLevel` methods?  The level set in the logger
   determines which severity of messages it will pass to its handlers.  The level
   set in each handler determines which messages that handler will send on.
 
@@ -774,29 +774,29 @@ What happens if no configuration is provided
 
 If no logging configuration is provided, it is possible to have a situation
 where a logging event needs to be output, but no handlers can be found to
-output the event. The behaviour of the logging package in these
-circumstances is dependent on the Python version.
+output the event.
 
-For versions of Python prior to 3.2, the behaviour is as follows:
+The event is output using a 'handler of last resort', stored in
+:data:`lastResort`. This internal handler is not associated with any
+logger, and acts like a :class:`~logging.StreamHandler` which writes the
+event description message to the current value of ``sys.stderr`` (therefore
+respecting any redirections which may be in effect). No formatting is
+done on the message - just the bare event description message is printed.
+The handler's level is set to ``WARNING``, so all events at this and
+greater severities will be output.
 
-* If *logging.raiseExceptions* is ``False`` (production mode), the event is
-  silently dropped.
+.. versionchanged:: 3.2
 
-* If *logging.raiseExceptions* is ``True`` (development mode), a message
-  'No handlers could be found for logger X.Y.Z' is printed once.
+   For versions of Python prior to 3.2, the behaviour is as follows:
 
-In Python 3.2 and later, the behaviour is as follows:
+   * If :data:`raiseExceptions` is ``False`` (production mode), the event is
+     silently dropped.
 
-* The event is output using a 'handler of last resort', stored in
-  ``logging.lastResort``. This internal handler is not associated with any
-  logger, and acts like a :class:`~logging.StreamHandler` which writes the
-  event description message to the current value of ``sys.stderr`` (therefore
-  respecting any redirections which may be in effect). No formatting is
-  done on the message - just the bare event description message is printed.
-  The handler's level is set to ``WARNING``, so all events at this and
-  greater severities will be output.
+   * If :data:`raiseExceptions` is ``True`` (development mode), a message
+     'No handlers could be found for logger X.Y.Z' is printed once.
 
-To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
+   To obtain the pre-3.2 behaviour,
+   :data:`lastResort` can be set to ``None``.
 
 .. _library-config:
 
@@ -998,7 +998,7 @@ Logged messages are formatted for presentation through instances of the
 use with the % operator and a dictionary.
 
 For formatting multiple messages in a batch, instances of
-:class:`~handlers.BufferingFormatter` can be used. In addition to the format
+:class:`BufferingFormatter` can be used. In addition to the format
 string (which is applied to each message in the batch), there is provision for
 header and trailer format strings.
 
@@ -1034,7 +1034,8 @@ 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
+.. 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.
@@ -1072,7 +1073,7 @@ You can write code like this::
                                             expensive_func2())
 
 so that if the logger's threshold is set above ``DEBUG``, the calls to
-:func:`expensive_func1` and :func:`expensive_func2` are never made.
+``expensive_func1`` and ``expensive_func2`` are never made.
 
 .. note:: In some cases, :meth:`~Logger.isEnabledFor` can itself be more
    expensive than you'd like (e.g. for deeply nested loggers where an explicit

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 4b756d10b4c586cd9a1c324198045096c6bbfe61..39eb41ce1f16708060ca3a199e617e4853240ce1 100644 (file)
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -531,12 +531,12 @@ subclasses. However, the :meth:`!__init__` method in subclasses needs to call
 
       This method should be called from handlers when an exception is encountered
       during an :meth:`emit` call. If the module-level attribute
-      ``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
+      :data:`raiseExceptions` is ``False``, exceptions get silently ignored. This is
       what is mostly wanted for a logging system - most users will not care about
       errors in the logging system, they are more interested in application
       errors. You could, however, replace this with a custom handler if you wish.
       The specified record is the one which was being processed when the exception
-      occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
+      occurred. (The default value of :data:`raiseExceptions` is ``True``, as that is
       more useful during development).
 
 
@@ -1494,6 +1494,18 @@ Module-Level Attributes
 
    .. versionadded:: 3.2
 
+.. attribute:: raiseExceptions
+
+   Used to see if exceptions during handling should be propagated.
+
+   Default: ``True``.
+
+   If :data:`raiseExceptions` is ``False``,
+   exceptions get silently ignored. This is what is mostly wanted
+   for a logging system - most users will not care about errors in
+   the logging system, they are more interested in application errors.
+
+
 Integration with the warnings module
 ------------------------------------
 

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 7eacb46d6299b3c0c374c28dfaee879a51992ab8..7127f30f240ce7a7ce4a494f89b555b5a26eb1b2 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -18,7 +18,6 @@ Doc/extending/extending.rst
 Doc/glossary.rst
 Doc/howto/descriptor.rst
 Doc/howto/enum.rst
-Doc/howto/logging.rst
 Doc/library/ast.rst
 Doc/library/asyncio-extending.rst
 Doc/library/asyncio-policy.rst