Some cleanup.

Author: ZeroIntensity

Doc/c-api/interp-lifecycle.rst

@@ -2,17 +2,16 @@
 
 .. _initialization:
 
-*******************************************
 Interpreter Initialization and Finalization
-*******************************************
+===========================================
 
 See :ref:`Python Initialization Configuration <init-config>` for details
 on how to configure the interpreter prior to initialization.
 
 .. _pre-init-safe:
 
 Before Python Initialization
-============================
+----------------------------
 
 In an application embedding  Python, the :c:func:`Py_Initialize` function must
 be called before using any other Python/C API functions; with the exception of
@@ -82,7 +81,7 @@ The following functions can be safely called before Python is initialized:
 .. _global-conf-vars:
 
 Global configuration variables
-==============================
+------------------------------
 
 Python has variables for the global configuration to control different features
 and options. By default, these flags are controlled by :ref:`command line
@@ -92,6 +91,7 @@ When a flag is set by an option, the value of the flag is the number of times
 that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
 to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
+
 .. c:var:: int Py_BytesWarningFlag
 
    This API is kept for backward compatibility: setting
@@ -106,6 +106,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_DebugFlag
 
    This API is kept for backward compatibility: setting
@@ -120,6 +121,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_DontWriteBytecodeFlag
 
    This API is kept for backward compatibility: setting
@@ -134,6 +136,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_FrozenFlag
 
    This API is kept for backward compatibility: setting
@@ -144,6 +147,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_HashRandomizationFlag
 
    This API is kept for backward compatibility: setting
@@ -159,6 +163,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_IgnoreEnvironmentFlag
 
    This API is kept for backward compatibility: setting
@@ -172,6 +177,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_InspectFlag
 
    This API is kept for backward compatibility: setting
@@ -187,6 +193,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_InteractiveFlag
 
    This API is kept for backward compatibility: setting
@@ -197,6 +204,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_IsolatedFlag
 
    This API is kept for backward compatibility: setting
@@ -212,6 +220,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_LegacyWindowsFSEncodingFlag
 
    This API is kept for backward compatibility: setting
@@ -231,6 +240,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_LegacyWindowsStdioFlag
 
    This API is kept for backward compatibility: setting
@@ -249,6 +259,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_NoSiteFlag
 
    This API is kept for backward compatibility: setting
@@ -264,6 +275,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_NoUserSiteDirectory
 
    This API is kept for backward compatibility: setting
@@ -278,6 +290,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_OptimizeFlag
 
    This API is kept for backward compatibility: setting
@@ -289,6 +302,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_QuietFlag
 
    This API is kept for backward compatibility: setting
@@ -303,6 +317,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_UnbufferedStdioFlag
 
    This API is kept for backward compatibility: setting
@@ -316,6 +331,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. deprecated-removed:: 3.12 3.15
 
+
 .. c:var:: int Py_VerboseFlag
 
    This API is kept for backward compatibility: setting
@@ -334,8 +350,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
 
 Initializing and finalizing the interpreter
-===========================================
-
+-------------------------------------------
 
 .. c:function:: void Py_Initialize()
 
@@ -555,9 +570,9 @@ Initializing and finalizing the interpreter
 
    .. versionadded:: 3.13
 
-Process-wide parameters
-=======================
 
+Process-wide parameters
+-----------------------
 
 .. c:function:: void Py_SetProgramName(const wchar_t *name)
 
@@ -755,6 +770,7 @@ Process-wide parameters
 
    .. deprecated-removed:: 3.11 3.15
 
+
 .. _cautions-regarding-runtime-finalization:
 
 Cautions regarding runtime finalization

Doc/c-api/subinterpreters.rst

@@ -433,7 +433,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 .. _advanced-debugging:
 
 Advanced Debugger Support
-=========================
+-------------------------
 
 These functions are only intended to be used by advanced debugging tools.
 

Doc/c-api/threads.rst

@@ -109,6 +109,45 @@ to be released to attach their thread state, allowing true multi-core parallelis
    For example, the standard :mod:`zlib` and :mod:`hashlib` modules detach the
    :term:`thread state <attached thread state>` when compressing or hashing data.
 
+APIs
+^^^^
+
+The following macros are normally used without a trailing semicolon; look for
+example usage in the Python source distribution.
+
+.. note::
+
+    These macros are still necessary on the :term:`free-threaded build` to prevent
+    deadlocks.
+
+.. c:macro:: Py_BEGIN_ALLOW_THREADS
+
+   This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
+   Note that it contains an opening brace; it must be matched with a following
+   :c:macro:`Py_END_ALLOW_THREADS` macro.  See above for further discussion of this
+   macro.
+
+
+.. c:macro:: Py_END_ALLOW_THREADS
+
+   This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
+   a closing brace; it must be matched with an earlier
+   :c:macro:`Py_BEGIN_ALLOW_THREADS` macro.  See above for further discussion of
+   this macro.
+
+
+.. c:macro:: Py_BLOCK_THREADS
+
+   This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
+   :c:macro:`Py_END_ALLOW_THREADS` without the closing brace.
+
+
+.. c:macro:: Py_UNBLOCK_THREADS
+
+   This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
+   :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
+   declaration.
+
 
 .. _gilstate:
 
@@ -178,6 +217,7 @@ the :term:`thread state` is targeting the correct interpreter::
    PyThreadState_Clear(tstate);
    PyThreadState_DeleteCurrent();
 
+
 .. _fork-and-threads:
 
 Cautions about fork()
@@ -318,45 +358,6 @@ C extensions.
       thread if the runtime is finalizing.
 
 
-Releasing the GIL
------------------
-
-The following macros are normally used without a trailing semicolon; look for
-example usage in the Python source distribution.
-
-.. note::
-
-    These macros are still necessary on the :term:`free-threaded build` to prevent
-    deadlocks.
-
-.. c:macro:: Py_BEGIN_ALLOW_THREADS
-
-   This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
-   Note that it contains an opening brace; it must be matched with a following
-   :c:macro:`Py_END_ALLOW_THREADS` macro.  See above for further discussion of this
-   macro.
-
-
-.. c:macro:: Py_END_ALLOW_THREADS
-
-   This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
-   a closing brace; it must be matched with an earlier
-   :c:macro:`Py_BEGIN_ALLOW_THREADS` macro.  See above for further discussion of
-   this macro.
-
-
-.. c:macro:: Py_BLOCK_THREADS
-
-   This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
-   :c:macro:`Py_END_ALLOW_THREADS` without the closing brace.
-
-
-.. c:macro:: Py_UNBLOCK_THREADS
-
-   This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
-   :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
-   declaration.
-
 GIL-state APIs
 --------------
 
@@ -626,7 +627,7 @@ Low-level APIs
 
 
 Asynchronous Notifications
---------------------------
+==========================
 
 A mechanism is provided to make asynchronous notifications to the main
 interpreter thread.  These notifications take the form of a function
@@ -708,7 +709,8 @@ pointer and a void pointer argument.
 
    .. versionchanged:: 3.7
       The type of the *id* parameter changed from :c:expr:`long` to
-      :c:expr:`unsigned long`.
+      :c:expr:`unsigned long`
+.
 
 .. _thread-local-storage: