From d12bd1ba1ab2575a3e4c5dfeccc77a969aa92988 Mon Sep 17 00:00:00 2001
From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Thu, 9 Oct 2025 16:20:34 +0100
Subject: [PATCH] =?utf8?q?[3.13]=20gh-101100:=20Fix=20reference=20warnings?=
 =?utf8?q?=20in=20`c-api/init.rst`=20document=E2=80=A6=20(#139833)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---
 Doc/c-api/init.rst   | 19 ++++++++++++++++---
 Doc/tools/.nitignore |  1 -
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 6a6d35d3ac56..c2026922c703 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1094,7 +1094,7 @@ acquire the :term:`GIL`.
 If any thread, other than the finalization thread, attempts to acquire the GIL
 during finalization, either explicitly via :c:func:`PyGILState_Ensure`,
 :c:macro:`Py_END_ALLOW_THREADS`, :c:func:`PyEval_AcquireThread`, or
-:c:func:`PyEval_AcquireLock`, or implicitly when the interpreter attempts to
+:c:func:`!PyEval_AcquireLock`, or implicitly when the interpreter attempts to
 reacquire it after having yielded it, the thread enters **a permanently blocked
 state** where it remains until the program exits.  In most cases this is
 harmless, but this can result in deadlock if a later stage of finalization
@@ -1228,6 +1228,19 @@ code, or when embedding the Python interpreter:
 The following functions use thread-local storage, and are not compatible
 with sub-interpreters:
 
+.. c:type:: PyGILState_STATE
+
+   The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
+   :c:func:`PyGILState_Release`.
+
+   .. c:enumerator:: PyGILState_LOCKED
+
+      The GIL was already held when :c:func:`PyGILState_Ensure` was called.
+
+   .. c:enumerator:: PyGILState_UNLOCKED
+
+      The GIL was not held when :c:func:`PyGILState_Ensure` was called.
+
 .. c:function:: PyGILState_STATE PyGILState_Ensure()
 
    Ensure that the current thread is ready to call the Python C API regardless
@@ -1372,11 +1385,11 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    must be held.
 
    .. versionchanged:: 3.9
-      This function now calls the :c:member:`PyThreadState.on_delete` callback.
+      This function now calls the :c:member:`!PyThreadState.on_delete` callback.
       Previously, that happened in :c:func:`PyThreadState_Delete`.
 
    .. versionchanged:: 3.13
-      The :c:member:`PyThreadState.on_delete` callback was removed.
+      The :c:member:`!PyThreadState.on_delete` callback was removed.
 
 
 .. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 5974339ac28d..8b9a88bd8a77 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -4,7 +4,6 @@
 
 Doc/c-api/descriptor.rst
 Doc/c-api/float.rst
-Doc/c-api/init.rst
 Doc/c-api/init_config.rst
 Doc/c-api/intro.rst
 Doc/c-api/module.rst
-- 
2.47.3