[Python-checkins] [3.11] gh-107298: Fix C API datetime documentation (GH-108034) (#108233)

[ambv]

https://github.com/python/cpython/commit/80c7ae00f10a374e1d79d1c2719056951fdd3421
commit: 80c7ae00f10a374e1d79d1c2719056951fdd3421
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2023-08-22T20:32:48+02:00
summary:

[3.11] gh-107298: Fix C API datetime documentation (GH-108034) (#108233)

(cherry picked from commit d63972e289e05b0d82e59f32f107312a8b3de7b5)

Co-authored-by: Serhiy Storchaka <storchaka at gmail.com>

files:
M Doc/c-api/datetime.rst
M Doc/tools/.nitignore

diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst
index 72fc07afbf1f4..97522da773477 100644
--- a/Doc/c-api/datetime.rst
+++ b/Doc/c-api/datetime.rst
@@ -8,11 +8,54 @@ DateTime Objects
 Various date and time objects are supplied by the :mod:`datetime` module.
 Before using any of these functions, the header file :file:`datetime.h` must be
 included in your source (note that this is not included by :file:`Python.h`),
-and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
+and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of
 the module initialisation function.  The macro puts a pointer to a C structure
-into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
+into a static variable, :c:data:`!PyDateTimeAPI`, that is used by the following
 macros.
 
+.. c:type:: PyDateTime_Date
+
+   This subtype of :c:type:`PyObject` represents a Python date object.
+
+.. c:type:: PyDateTime_DateTime
+
+   This subtype of :c:type:`PyObject` represents a Python datetime object.
+
+.. c:type:: PyDateTime_Time
+
+   This subtype of :c:type:`PyObject` represents a Python time object.
+
+.. c:type:: PyDateTime_Delta
+
+   This subtype of :c:type:`PyObject` represents the difference between two datetime values.
+
+.. c:var:: PyTypeObject PyDateTime_DateType
+
+   This instance of :c:type:`PyTypeObject` represents the Python date type;
+   it is the same object as :class:`datetime.date` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DateTimeType
+
+   This instance of :c:type:`PyTypeObject` represents the Python datetime type;
+   it is the same object as :class:`datetime.datetime` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TimeType
+
+   This instance of :c:type:`PyTypeObject` represents the Python time type;
+   it is the same object as :class:`datetime.time` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DeltaType
+
+   This instance of :c:type:`PyTypeObject` represents Python type for
+   the difference between two datetime values;
+   it is the same object as :class:`datetime.timedelta` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TZInfoType
+
+   This instance of :c:type:`PyTypeObject` represents the Python time zone info type;
+   it is the same object as :class:`datetime.tzinfo` in the Python layer.
+
+
 Macro for access to the UTC singleton:
 
 .. c:var:: PyObject* PyDateTime_TimeZone_UTC
@@ -28,7 +71,7 @@ Type-check macros:
 .. c:function:: int PyDate_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
-   :c:data:`PyDateTime_DateType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DateType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -41,7 +84,7 @@ Type-check macros:
 .. c:function:: int PyDateTime_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
-   :c:data:`PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -54,7 +97,7 @@ Type-check macros:
 .. c:function:: int PyTime_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
-   :c:data:`PyDateTime_TimeType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_TimeType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -67,7 +110,7 @@ Type-check macros:
 .. c:function:: int PyDelta_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
-   :c:data:`PyDateTime_DeltaType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DeltaType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -80,7 +123,7 @@ Type-check macros:
 .. c:function:: int PyTZInfo_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
-   :c:data:`PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -133,7 +176,7 @@ Macros to create objects:
    :class:`datetime.timedelta` objects.
 
 
-.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
+.. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset)
 
    Return a :class:`datetime.timezone` object with an unnamed fixed offset
    represented by the *offset* argument.
@@ -141,7 +184,7 @@ Macros to create objects:
    .. versionadded:: 3.7
 
 
-.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
+.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
 
    Return a :class:`datetime.timezone` object with a fixed offset represented
    by the *offset* argument and with tzname *name*.
@@ -150,8 +193,8 @@ Macros to create objects:
 
 
 Macros to extract fields from date objects.  The argument must be an instance of
-:c:data:`PyDateTime_Date`, including subclasses (such as
-:c:data:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
+:c:type:`PyDateTime_Date`, including subclasses (such as
+:c:type:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
 not checked:
 
 .. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
@@ -170,7 +213,7 @@ not checked:
 
 
 Macros to extract fields from datetime objects.  The argument must be an
-instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
+instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument
 must not be ``NULL``, and the type is not checked:
 
 .. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
@@ -208,7 +251,7 @@ must not be ``NULL``, and the type is not checked:
 
 
 Macros to extract fields from time objects.  The argument must be an instance of
-:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
+:c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
 and the type is not checked:
 
 .. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
@@ -246,7 +289,7 @@ and the type is not checked:
 
 
 Macros to extract fields from time delta objects.  The argument must be an
-instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
+instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must
 not be ``NULL``, and the type is not checked:
 
 .. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index c8f3080cb6edd..4021f97e34f7f 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -2,7 +2,6 @@
 # as tested on the CI via check-warnings.py in reusable-docs.yml.
 # Keep lines sorted lexicographically to help avoid merge conflicts.
 
-Doc/c-api/datetime.rst
 Doc/c-api/descriptor.rst
 Doc/c-api/exceptions.rst
 Doc/c-api/file.rst