From 4b9098bfc39a13a601ae1d287cd9e3ac6cbb7a68 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 19 Aug 2023 15:10:37 +0200 Subject: [PATCH 1/3] Docs: Fix Sphinx warnings in logging.rst - Add missing markup to some methods - Silence links to __init__ methods --- Doc/library/logging.rst | 12 ++++++------ Doc/tools/.nitignore | 1 - 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 49e870e9e2479b..4523480f766083 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -439,7 +439,7 @@ Handler Objects Handlers have the following attributes and methods. Note that :class:`Handler` is never instantiated directly; this class acts as a base for more useful -subclasses. However, the :meth:`__init__` method in subclasses needs to call +subclasses. However, the :meth:`!__init__` method in subclasses needs to call :meth:`Handler.__init__`. .. class:: Handler @@ -1034,12 +1034,12 @@ interchangeably. to :class:`LoggerAdapter`. These methods delegate to the underlying logger. .. versionchanged:: 3.6 - Attribute :attr:`manager` and method :meth:`_log` were added, which + Attribute :attr:`!manager` and method :meth:`!_log` were added, which delegate to the underlying logger and allow adapters to be nested. .. versionchanged:: 3.13 - Remove the undocumented ``warn()`` method which was an alias to the - ``warning()`` method. + Remove the undocumented :meth:`!warn`` method which was an alias to the + :meth:`!warning` method. .. versionchanged:: 3.13 The *merge_extra* argument was added. @@ -1430,8 +1430,8 @@ functions. .. function:: setLoggerClass(klass) Tells the logging system to use the class *klass* when instantiating a logger. - The class should define :meth:`__init__` such that only a name argument is - required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This + The class should define :meth:`!__init__` such that only a name argument is + required, and the :meth:`!__init__` should call :meth:`!Logger.__init__`. This function is typically called before any loggers are instantiated by applications which need to use custom logger behavior. After this call, as at any other time, do not instantiate loggers directly using the subclass: continue to use diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 654287cc50b55b..5bf94ecba36001 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -92,7 +92,6 @@ Doc/library/inspect.rst Doc/library/locale.rst Doc/library/logging.config.rst Doc/library/logging.handlers.rst -Doc/library/logging.rst Doc/library/lzma.rst Doc/library/mailbox.rst Doc/library/mmap.rst From 51acca63cde10a72ac7661893d826f250593762c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 19 Aug 2023 19:00:23 +0200 Subject: [PATCH 2/3] Address review: add missing indent --- Doc/library/logging.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 4523480f766083..7a183a81575667 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1028,21 +1028,25 @@ methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`, counterparts in :class:`Logger`, so you can use the two types of instances interchangeably. -.. versionchanged:: 3.2 - The :meth:`~Logger.isEnabledFor`, :meth:`~Logger.getEffectiveLevel`, - :meth:`~Logger.setLevel` and :meth:`~Logger.hasHandlers` methods were added - to :class:`LoggerAdapter`. These methods delegate to the underlying logger. + .. versionchanged:: 3.2 + + The :meth:`~Logger.isEnabledFor`, :meth:`~Logger.getEffectiveLevel`, + :meth:`~Logger.setLevel` and :meth:`~Logger.hasHandlers` methods were added + to :class:`LoggerAdapter`. These methods delegate to the underlying logger. + + .. versionchanged:: 3.6 -.. versionchanged:: 3.6 - Attribute :attr:`!manager` and method :meth:`!_log` were added, which - delegate to the underlying logger and allow adapters to be nested. + Attribute :attr:`!manager` and method :meth:`!_log` were added, which + delegate to the underlying logger and allow adapters to be nested. -.. versionchanged:: 3.13 - Remove the undocumented :meth:`!warn`` method which was an alias to the - :meth:`!warning` method. + .. versionchanged:: 3.13 + + Remove the undocumented :meth:`!warn`` method which was an alias to the + :meth:`!warning` method. + + .. versionchanged:: 3.13 -.. versionchanged:: 3.13 - The *merge_extra* argument was added. + The *merge_extra* argument was added. Thread Safety From bc520c5a2376ab1fc3bdf286f717fa5b125a7018 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 19 Aug 2023 19:52:07 +0100 Subject: [PATCH 3/3] Indent an additional paragraph --- Doc/library/logging.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 7a183a81575667..97a0b82b78b1b3 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1019,14 +1019,14 @@ information into logging calls. For a usage example, see the section on 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the (possibly modified) versions of the arguments passed in. -In addition to the above, :class:`LoggerAdapter` supports the following -methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`, -:meth:`~Logger.warning`, :meth:`~Logger.error`, :meth:`~Logger.exception`, -:meth:`~Logger.critical`, :meth:`~Logger.log`, :meth:`~Logger.isEnabledFor`, -:meth:`~Logger.getEffectiveLevel`, :meth:`~Logger.setLevel` and -:meth:`~Logger.hasHandlers`. These methods have the same signatures as their -counterparts in :class:`Logger`, so you can use the two types of instances -interchangeably. + In addition to the above, :class:`LoggerAdapter` supports the following + methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`, + :meth:`~Logger.warning`, :meth:`~Logger.error`, :meth:`~Logger.exception`, + :meth:`~Logger.critical`, :meth:`~Logger.log`, :meth:`~Logger.isEnabledFor`, + :meth:`~Logger.getEffectiveLevel`, :meth:`~Logger.setLevel` and + :meth:`~Logger.hasHandlers`. These methods have the same signatures as their + counterparts in :class:`Logger`, so you can use the two types of instances + interchangeably. .. versionchanged:: 3.2