[3.12] NEWS: Fix Sphinx warnings and increase threshold for new news nits (GH-121482) (#121514)

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

Author: hugovk

Doc/conf.py

@@ -256,6 +256,9 @@
     ('c:data', 'PyExc_UnicodeWarning'),
     ('c:data', 'PyExc_UserWarning'),
     ('c:data', 'PyExc_Warning'),
+    # Undocumented public C macros
+    ('c:macro', 'Py_BUILD_ASSERT'),
+    ('c:macro', 'Py_BUILD_ASSERT_EXPR'),
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.

Doc/library/profile.rst

@@ -692,7 +692,7 @@ you are using :class:`profile.Profile` or :class:`cProfile.Profile`,
    As the :class:`cProfile.Profile` class cannot be calibrated, custom timer
    functions should be used with care and should be as fast as possible.  For
    the best results with a custom timer, it might be necessary to hard-code it
-   in the C source of the internal :mod:`_lsprof` module.
+   in the C source of the internal :mod:`!_lsprof` module.
 
 Python 3.3 adds several new functions in :mod:`time` that can be used to make
 precise measurements of process or wall-clock time. For example, see

Doc/tools/check-warnings.py

@@ -14,7 +14,7 @@
 from typing import TextIO
 
 # Fail if NEWS nit found before this line number
-NEWS_NIT_THRESHOLD = 200
+NEWS_NIT_THRESHOLD = 300
 
 # Exclude these whether they're dirty or clean,
 # because they trigger a rebuild of dirty files.

Doc/whatsnew/3.4.rst

@@ -1495,7 +1495,7 @@ The dictionary returned by :meth:`.SSLSocket.getpeercert` contains additional
 stat
 ----
 
-The :mod:`stat` module is now backed by a C implementation in :mod:`_stat`. A C
+The :mod:`stat` module is now backed by a C implementation in :mod:`!_stat`. A C
 implementation is required as most of the values aren't standardized and
 are platform-dependent.  (Contributed by Christian Heimes in :issue:`11016`.)
 

Doc/whatsnew/3.5.rst

@@ -1935,8 +1935,8 @@ specifying the namespace in which the code will be running.
 tkinter
 -------
 
-The :mod:`tkinter._fix` module used for setting up the Tcl/Tk environment
-on Windows has been replaced by a private function in the :mod:`_tkinter`
+The :mod:`!tkinter._fix` module used for setting up the Tcl/Tk environment
+on Windows has been replaced by a private function in the :mod:`!_tkinter`
 module which makes no permanent changes to environment variables.
 (Contributed by Zachary Ware in :issue:`20035`.)
 

Doc/whatsnew/3.7.rst

@@ -2048,7 +2048,7 @@ The :mod:`macpath` is now deprecated and will be removed in Python 3.8.
 threading
 ---------
 
-:mod:`dummy_threading` and :mod:`_dummy_thread` have been deprecated.  It is
+:mod:`!dummy_threading` and :mod:`!_dummy_thread` have been deprecated.  It is
 no longer possible to build Python with threading disabled.
 Use :mod:`threading` instead.
 (Contributed by Antoine Pitrou in :issue:`31370`.)
@@ -2184,7 +2184,7 @@ The following features and APIs have been removed from Python 3.7:
   ``socket.socketpair`` on Python 3.5 and newer.
 
 * :mod:`asyncio` no longer exports the :mod:`selectors` and
-  :mod:`_overlapped` modules as ``asyncio.selectors`` and
+  :mod:`!_overlapped` modules as ``asyncio.selectors`` and
   ``asyncio._overlapped``. Replace ``from asyncio import selectors`` with
   ``import selectors``.
 

Misc/HISTORY

@@ -3952,7 +3952,7 @@ Library
 - Issue #18626: the inspect module now offers a basic command line
   introspection interface (Initial patch by Claudiu Popa)
 
-- Issue #3015: Fixed tkinter with wantobject=False.  Any Tcl command call
+- Issue #3015: Fixed tkinter with ``wantobjects=False``.  Any Tcl command call
   returned empty string.
 
 - Issue #19037: The mailbox module now makes all changes to maildir files

Misc/NEWS.d/3.10.0a1.rst

@@ -97,7 +97,7 @@ convention. Patch by Donghee Na.
 .. nonce: aJS9B3
 .. section: Core and Builtins
 
-Port the :mod:`_bisect` module to the multi-phase initialization API
+Port the :mod:`!_bisect` module to the multi-phase initialization API
 (:pep:`489`).
 
 ..
@@ -128,7 +128,7 @@ Taskaya.
 .. nonce: lh335O
 .. section: Core and Builtins
 
-Port the :mod:`_lsprof` extension module to multi-phase initialization
+Port the :mod:`!_lsprof` extension module to multi-phase initialization
 (:pep:`489`).
 
 ..
@@ -148,7 +148,7 @@ Port the :mod:`cmath` extension module to multi-phase initialization
 .. nonce: jiXmyT
 .. section: Core and Builtins
 
-Port the :mod:`_scproxy` extension module to multi-phase initialization
+Port the :mod:`!_scproxy` extension module to multi-phase initialization
 (:pep:`489`).
 
 ..
@@ -168,7 +168,7 @@ Port the :mod:`termios` extension module to multi-phase initialization
 .. nonce: QuDIut
 .. section: Core and Builtins
 
-Convert the :mod:`_sha256` extension module types to heap types.
+Convert the :mod:`!_sha256` extension module types to heap types.
 
 ..
 
@@ -187,7 +187,7 @@ classes with a huge amount of arguments. Patch by Pablo Galindo.
 .. nonce: CnRME3
 .. section: Core and Builtins
 
-Port the :mod:`_overlapped` extension module to multi-phase initialization
+Port the :mod:`!_overlapped` extension module to multi-phase initialization
 (:pep:`489`).
 
 ..
@@ -197,7 +197,7 @@ Port the :mod:`_overlapped` extension module to multi-phase initialization
 .. nonce: X9CZgo
 .. section: Core and Builtins
 
-Port the :mod:`_curses_panel` extension module to multi-phase initialization
+Port the :mod:`!_curses_panel` extension module to multi-phase initialization
 (:pep:`489`).
 
 ..
@@ -207,7 +207,7 @@ Port the :mod:`_curses_panel` extension module to multi-phase initialization
 .. nonce: 5jZymK
 .. section: Core and Builtins
 
-Port the :mod:`_opcode` extension module to multi-phase initialization
+Port the :mod:`!_opcode` extension module to multi-phase initialization
 (:pep:`489`).
 
 ..
@@ -282,7 +282,7 @@ initialized ``_ast`` module.
 .. nonce: vcxSUa
 .. section: Core and Builtins
 
-Convert :mod:`_operator` to use :c:func:`PyType_FromSpec`.
+Convert :mod:`!_operator` to use :c:func:`PyType_FromSpec`.
 
 ..
 
@@ -291,7 +291,7 @@ Convert :mod:`_operator` to use :c:func:`PyType_FromSpec`.
 .. nonce: fubBkb
 .. section: Core and Builtins
 
-Port :mod:`_sha3` to multi-phase init.  Convert static types to heap types.
+Port :mod:`!_sha3` to multi-phase init.  Convert static types to heap types.
 
 ..
 
@@ -300,7 +300,7 @@ Port :mod:`_sha3` to multi-phase init.  Convert static types to heap types.
 .. nonce: FC13e7
 .. section: Core and Builtins
 
-Port the :mod:`_blake2` extension module to the multi-phase initialization
+Port the :mod:`!_blake2` extension module to the multi-phase initialization
 API (:pep:`489`).
 
 ..
@@ -339,7 +339,7 @@ The output of ``python --help`` contains now only ASCII characters.
 .. nonce: O0d3ym
 .. section: Core and Builtins
 
-Port the :mod:`_sha1`, :mod:`_sha512`, and :mod:`_md5` extension modules to
+Port the :mod:`!_sha1`, :mod:`!_sha512`, and :mod:`!_md5` extension modules to
 multi-phase initialization API (:pep:`489`).
 
 ..
@@ -636,7 +636,7 @@ Remove the remaining files from the old parser and the :mod:`symbol` module.
 .. nonce: _yI-ax
 .. section: Core and Builtins
 
-Convert :mod:`_bz2` to use :c:func:`PyType_FromSpec`.
+Convert :mod:`!_bz2` to use :c:func:`PyType_FromSpec`.
 
 ..
 
@@ -666,7 +666,7 @@ by Brandt Bucher.
 .. nonce: 61iyYh
 .. section: Core and Builtins
 
-Port :mod:`_gdbm` to multiphase initialization.
+Port :mod:`!_gdbm` to multiphase initialization.
 
 ..
 
@@ -696,7 +696,7 @@ for emitting syntax errors. Patch by Pablo Galindo.
 .. nonce: mmlp3Q
 .. section: Core and Builtins
 
-Port :mod:`_dbm` to multiphase initialization.
+Port :mod:`!_dbm` to multiphase initialization.
 
 ..
 
@@ -1010,7 +1010,7 @@ Port :mod:`mmap` to multiphase initialization.
 .. nonce: Kfe9fT
 .. section: Core and Builtins
 
-Port :mod:`_lzma` to multiphase initialization.
+Port :mod:`!_lzma` to multiphase initialization.
 
 ..
 

Misc/NEWS.d/3.10.0a2.rst

@@ -362,7 +362,7 @@ plistlib: fix parsing XML plists with hexadecimal integer values
 .. nonce: 85BsRA
 .. section: Library
 
-Fix an incorrectly formatted error from :meth:`_codecs.charmap_decode` when
+Fix an incorrectly formatted error from :meth:`!_codecs.charmap_decode` when
 called with a mapped value outside the range of valid Unicode code points.
 PR by Max Bernstein.
 

Misc/NEWS.d/3.10.0a3.rst

@@ -1386,7 +1386,7 @@ Python already implicitly installs signal handlers: see
 
 The ``Py_TRASHCAN_BEGIN`` macro no longer accesses PyTypeObject attributes,
 but now can get the condition by calling the new private
-:c:func:`_PyTrash_cond()` function which hides implementation details.
+:c:func:`!_PyTrash_cond()` function which hides implementation details.
 
 ..
 

Misc/NEWS.d/3.10.0a4.rst

@@ -193,7 +193,7 @@ subinterpreters. Patch by Victor Stinner.
 .. nonce: j7nl6A
 .. section: Core and Builtins
 
-Make :c:func:`_PyUnicode_FromId` function compatible with subinterpreters.
+Make :c:func:`!_PyUnicode_FromId` function compatible with subinterpreters.
 Each interpreter now has an array of identifier objects (interned strings
 decoded from UTF-8). Patch by Victor Stinner.
 
@@ -367,7 +367,7 @@ uses "options" instead.
 .. nonce: Quy3zn
 .. section: Library
 
-Port the :mod:`_thread` extension module to the multiphase initialization
+Port the :mod:`!_thread` extension module to the multiphase initialization
 API (:pep:`489`) and convert its static types to heap types.
 
 ..
@@ -960,8 +960,8 @@ explicitly and so not exported.
 .. nonce: Je08Ny
 .. section: C API
 
-Remove the private :c:func:`_Py_fopen` function which is no longer needed.
-Use :c:func:`_Py_wfopen` or :c:func:`_Py_fopen_obj` instead. Patch by Victor
+Remove the private :c:func:`!_Py_fopen` function which is no longer needed.
+Use :c:func:`!_Py_wfopen` or :c:func:`!_Py_fopen_obj` instead. Patch by Victor
 Stinner.
 
 ..

Misc/NEWS.d/3.10.0a5.rst

@@ -108,7 +108,7 @@ a slice at the start of the ``bytearray`` to a shorter byte string).
 .. nonce: WfTdfg
 .. section: Core and Builtins
 
-Fix the :c:func:`_PyUnicode_FromId` function (_Py_IDENTIFIER(var) API) when
+Fix the :c:func:`!_PyUnicode_FromId` function (_Py_IDENTIFIER(var) API) when
 :c:func:`Py_Initialize` / :c:func:`Py_Finalize` is called multiple times:
 preserve ``_PyRuntime.unicode_ids.next_index`` value.
 

Misc/NEWS.d/3.10.0a6.rst

@@ -315,7 +315,7 @@ Adds :const:`resource.RLIMIT_KQUEUES` constant from FreeBSD to the
 .. section: Library
 
 Make the pure Python implementation of :mod:`xml.etree.ElementTree` behave
-the same as the C implementation (:mod:`_elementree`) regarding default
+the same as the C implementation (:mod:`!_elementree`) regarding default
 attribute values (by not setting ``specified_attributes=1``).
 
 ..

Misc/NEWS.d/3.10.0a7.rst

@@ -83,7 +83,7 @@ instruction dispatch a bit.
 .. nonce: PhaT-B
 .. section: Core and Builtins
 
-Fix reference leak in the :mod:`_hashopenssl` extension. Patch by Pablo
+Fix reference leak in the :mod:`!_hashopenssl` extension. Patch by Pablo
 Galindo.
 
 ..

Misc/NEWS.d/3.10.0b1.rst

@@ -182,7 +182,7 @@ normally be possible, but might occur in some unusual circumstances.
 .. nonce: u5Y6bS
 .. section: Core and Builtins
 
-Importing the :mod:`_signal` module in a subinterpreter has no longer side
+Importing the :mod:`!_signal` module in a subinterpreter has no longer side
 effects.
 
 ..
@@ -776,11 +776,11 @@ builtins.open() is now io.open().
 .. nonce: o1zEk_
 .. section: Library
 
-The Python :func:`_pyio.open` function becomes a static method to behave as
+The Python :func:`!_pyio.open` function becomes a static method to behave as
 :func:`io.open` built-in function: don't become a bound method when stored
 as a class variable. It becomes possible since static methods are now
-callable in Python 3.10. Moreover, :func:`_pyio.OpenWrapper` becomes a
-simple alias to :func:`_pyio.open`. Patch by Victor Stinner.
+callable in Python 3.10. Moreover, :func:`!_pyio.OpenWrapper` becomes a
+simple alias to :func:`!_pyio.open`. Patch by Victor Stinner.
 
 ..
 

Misc/NEWS.d/3.11.0a1.rst

@@ -613,7 +613,7 @@ Rename ``types.Union`` to ``types.UnionType``.
 .. section: Core and Builtins
 
 Expose specialization stats in python via
-:func:`_opcode.get_specialization_stats`.
+:func:`!_opcode.get_specialization_stats`.
 
 ..
 
@@ -1701,7 +1701,7 @@ Remove many old deprecated :mod:`unittest` features:
 .. nonce: y1kEfP
 .. section: Library
 
-Remove the deprecated ``split()`` method of :class:`_tkinter.TkappType`.
+Remove the deprecated ``split()`` method of :class:`!_tkinter.TkappType`.
 Patch by Erlend E. Aasland.
 
 ..
@@ -2298,9 +2298,9 @@ Adopt *binacii.a2b_base64*'s strict mode in *base64.b64decode*.
 .. nonce: ThuDMI
 .. section: Library
 
-Fixed a bug in the :mod:`_ssl` module that was throwing :exc:`OverflowError`
-when using :meth:`_ssl._SSLSocket.write` and :meth:`_ssl._SSLSocket.read`
-for a big value of the ``len`` parameter. Patch by Pablo Galindo
+Fixed a bug in the :mod:`!_ssl` module that was throwing :exc:`OverflowError`
+when using :meth:`!_ssl._SSLSocket.write` and :meth:`!_ssl._SSLSocket.read`
+for a big value of the ``len`` parameter. Patch by Pablo Galindo.
 
 ..
 
@@ -2398,7 +2398,7 @@ class in the interactive session. Instead of :exc:`TypeError`, it should be
 .. nonce: R3IcM1
 .. section: Library
 
-Fix memory leak in :func:`_tkinter._flatten` if it is called with a sequence
+Fix memory leak in :func:`!_tkinter._flatten` if it is called with a sequence
 or set, but not list or tuple.
 
 ..
@@ -4187,7 +4187,7 @@ Add calls of :func:`gc.collect` in tests to support PyPy.
 .. nonce: mQZdXU
 .. section: Tests
 
-Made tests relying on the :mod:`_asyncio` C extension module optional to
+Made tests relying on the :mod:`!_asyncio` C extension module optional to
 allow running on alternative Python implementations. Patch by Serhiy
 Storchaka.
 

Misc/NEWS.d/3.11.0a2.rst

@@ -15,7 +15,7 @@ Improve the :exc:`SyntaxError` message when using ``True``, ``None`` or
 .. section: Core and Builtins
 
 :data:`sys.stdlib_module_names` now contains the macOS-specific module
-:mod:`_scproxy`.
+:mod:`!_scproxy`.
 
 ..
 
@@ -1023,7 +1023,7 @@ compile shared modules.
 .. nonce: 61gM2A
 .. section: Build
 
-:mod:`pyexpat` and :mod:`_elementtree` no longer define obsolete macros
+:mod:`pyexpat` and :mod:`!_elementtree` no longer define obsolete macros
 ``HAVE_EXPAT_CONFIG_H`` and ``USE_PYEXPAT_CAPI``. ``XML_POOR_ENTROPY`` is
 now defined in ``expat_config.h``.
 

Misc/NEWS.d/3.11.0a3.rst

@@ -27,7 +27,7 @@ invalid targets. Patch by Pablo Galindo
 .. nonce: 3TmTSw
 .. section: Core and Builtins
 
-:c:func:`_PyErr_ChainStackItem` no longer normalizes ``exc_info`` (including
+:c:func:`!_PyErr_ChainStackItem` no longer normalizes ``exc_info`` (including
 setting the traceback on the exception instance) because ``exc_info`` is
 always normalized.
 

Misc/NEWS.d/3.11.0a4.rst

@@ -258,7 +258,7 @@ instruction which performs the same operation, but without the loop.
 .. nonce: ADVaPT
 .. section: Core and Builtins
 
-The code called from :c:func:`_PyErr_Display` was refactored to improve
+The code called from :c:func:`!_PyErr_Display` was refactored to improve
 error handling. It now exits immediately upon an unrecoverable error.
 
 ..