From be1c72a45d54cdd35e0a830e18224c4c74be808c Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Sat, 8 Nov 2025 10:47:09 -0500
Subject: [PATCH 1/4] gh-141004: Document `PyErr_ProgramTextObject` and
 `PyErr_ProgramText` (GH-141250)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---
 Doc/c-api/exceptions.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index f525ee7a0461fe..c58aa659e1b1b4 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -331,6 +331,23 @@ For convenience, some of these functions will always return a
    use.
 
 
+.. c:function:: PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)
+
+   Get the source line in *filename* at line *lineno*. *filename* should be a
+   Python :class:`str` object.
+
+   On success, this function returns a Python string object with the found line.
+   On failure, this function returns ``NULL`` without an exception set.
+
+
+.. c:function:: PyObject *PyErr_ProgramText(const char *filename, int lineno)
+
+   Similar to :c:func:`PyErr_ProgramTextObject`, but *filename* is a
+   :c:expr:`const char *`, which is decoded with the
+   :term:`filesystem encoding and error handler`, instead of a
+   Python object reference.
+
+
 Issuing warnings
 ================
 

From 5e5fc0404ed983bb37a19793a5c802d0d9852e5d Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Sat, 8 Nov 2025 12:29:31 -0500
Subject: [PATCH 2/4] gh-141004: Document `PyBUF_WRITEABLE` (GH-141255)

---
 Doc/c-api/buffer.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index d3081894eadaf5..6bb72a2312be3b 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -261,6 +261,10 @@ readonly, format
       MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE`
       can be used to request a simple writable buffer.
 
+   .. c:macro:: PyBUF_WRITEABLE
+
+      This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`.
+
    .. c:macro:: PyBUF_FORMAT
 
       Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST

From 545299773b40fb589cbd5e54d1d597207d9a2a76 Mon Sep 17 00:00:00 2001
From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Sat, 8 Nov 2025 18:12:03 +0000
Subject: [PATCH 3/4] gh-141004: Document the `PyDoc_VAR` macro (GH-141263)

---
 Doc/c-api/intro.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index acce3dc215d157..4e7d1630ab3da6 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -235,7 +235,7 @@ complete listing.
 
 .. c:macro:: PyDoc_STRVAR(name, str)
 
-   Creates a variable with name ``name`` that can be used in docstrings.
+   Creates a variable with name *name* that can be used in docstrings.
    If Python is built without docstrings, the value will be empty.
 
    Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
@@ -267,6 +267,15 @@ complete listing.
           {NULL, NULL}
       };
 
+.. c:macro:: PyDoc_VAR(name)
+
+   Declares a static character array variable with the given name *name*.
+
+   For example::
+
+      PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
+                                        "to the tropics and subtropics of the Eastern Hemisphere.");
+
 
 .. _api-objects:
 

From 0ac890bea79d3e0162c8909b0999f626f1141d89 Mon Sep 17 00:00:00 2001
From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Sat, 8 Nov 2025 19:22:05 +0000
Subject: [PATCH 4/4] gh-141004: Document `Py_BUILD_ASSERT*` macros (GH-141266)

---
 Doc/c-api/intro.rst | 23 +++++++++++++++++++++++
 Doc/conf.py         |  3 ---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 4e7d1630ab3da6..6e1a9dcb35543b 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -233,6 +233,29 @@ complete listing.
 
    .. versionadded:: 3.4
 
+.. c:macro:: Py_BUILD_ASSERT(cond)
+
+   Asserts a compile-time condition *cond*, as a statement.
+   The build will fail if the condition is false or cannot be evaluated at compile time.
+
+   For example::
+
+      Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_BUILD_ASSERT_EXPR(cond)
+
+   Asserts a compile-time condition *cond*, as an expression that evaluates to ``0``.
+   The build will fail if the condition is false or cannot be evaluated at compile time.
+
+   For example::
+
+      #define foo_to_char(foo) \
+          ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))
+
+   .. versionadded:: 3.3
+
 .. c:macro:: PyDoc_STRVAR(name, str)
 
    Creates a variable with name *name* that can be used in docstrings.
diff --git a/Doc/conf.py b/Doc/conf.py
index f1dda10052e109..0f1412d1007dc2 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -226,9 +226,6 @@
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [
-    # 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.