python
diff --git a/‎.github/workflows/reusable-docs.yml
Lines changed: 24 additions & 9 deletions b/‎.github/workflows/reusable-docs.yml
Lines changed: 24 additions & 9 deletions
diff --git a/‎.pre-commit-config.yaml
Lines changed: 1 addition & 1 deletion b/‎.pre-commit-config.yaml
Lines changed: 1 addition & 1 deletion
diff --git a/‎Doc/c-api/datetime.rst
Lines changed: 57 additions & 14 deletions b/‎Doc/c-api/datetime.rst
Lines changed: 57 additions & 14 deletions
diff --git a/‎Doc/faq/design.rst
Lines changed: 2 additions & 2 deletions b/‎Doc/faq/design.rst
Lines changed: 2 additions & 2 deletions
diff --git a/‎Doc/faq/gui.rst
Lines changed: 5 additions & 4 deletions b/‎Doc/faq/gui.rst
Lines changed: 5 additions & 4 deletions
diff --git a/‎Doc/faq/library.rst
Lines changed: 8 additions & 5 deletions b/‎Doc/faq/library.rst
Lines changed: 8 additions & 5 deletions
diff --git a/‎Doc/faq/programming.rst
Lines changed: 3 additions & 3 deletions b/‎Doc/faq/programming.rst
Lines changed: 3 additions & 3 deletions
@@ -16,8 +16,30 @@ jobs:
     name: 'Docs'
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    env:
+      branch_base: 'origin/${{ github.event.pull_request.base.ref }}'
+      branch_pr: 'origin/${{ github.event.pull_request.head.ref }}'
+      refspec_base: '+${{ github.event.pull_request.base.sha }}:remotes/origin/${{ github.event.pull_request.base.ref }}'
+      refspec_pr: '+${{ github.event.pull_request.head.sha }}:remotes/origin/${{ github.event.pull_request.head.ref }}'
     steps:
-    - uses: actions/checkout@v3
+    - name: 'Check out latest PR branch commit'
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+    # Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
+    - name: 'Fetch commits to get branch diff'
+      run: |
+        # Fetch enough history to find a common ancestor commit (aka merge-base):
+        git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \
+          --no-tags --prune --no-recurse-submodules
+
+        # This should get the oldest commit in the local fetched history (which may not be the commit the PR branched from):
+        COMMON_ANCESTOR=$( git rev-list --first-parent --max-parents=0 --max-count=1 ${{ env.branch_pr }} )
+        DATE=$( git log --date=iso8601 --format=%cd "${COMMON_ANCESTOR}" )
+
+        # Get all commits since that commit date from the base branch (eg: master or main):
+        git fetch origin ${{ env.refspec_base }} --shallow-since="${DATE}" \
+          --no-tags --prune --no-recurse-submodules
     - name: 'Set up Python'
       uses: actions/setup-python@v4
       with:
@@ -28,13 +50,6 @@ jobs:
       run: make -C Doc/ venv
 
     # To annotate PRs with Sphinx nitpicks (missing references)
-    - name: 'Get list of changed files'
-      if: github.event_name == 'pull_request'
-      id: changed_files
-      uses: Ana06/get-changed-files@v2.2.0
-      with:
-        filter: "Doc/**"
-        format: csv  # works for paths with spaces
     - name: 'Build HTML documentation'
       continue-on-error: true
       run: |
@@ -45,7 +60,7 @@ jobs:
       if: github.event_name == 'pull_request'
       run: |
         python Doc/tools/check-warnings.py \
-          --check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
+          --annotate-diff '${{ env.branch_base }}' '${{ env.branch_pr }}' \
           --fail-if-regression \
           --fail-if-improved
 
 
@@ -14,5 +14,5 @@ repos:
     hooks:
       - id: sphinx-lint
         args: [--enable=default-role]
-        files: ^Doc/
+        files: ^Doc/|^Misc/NEWS.d/next/
         types: [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,15 +176,15 @@ 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.
 
    .. 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)
 
@@ -584,9 +584,9 @@ exhaustive test suites that exercise every line of code in a module.
 An appropriate testing discipline can help build large complex applications in
 Python as well as having interface specifications would.  In fact, it can be
 better because an interface specification cannot test certain properties of a
-program.  For example, the :meth:`list.append` method is expected to add new elements
+program.  For example, the :meth:`!list.append` method is expected to add new elements
 to the end of some internal list; an interface specification cannot test that
-your :meth:`list.append` implementation will actually do this correctly, but it's
+your :meth:`!list.append` implementation will actually do this correctly, but it's
 trivial to check this property in a test suite.
 
 Writing test suites is very helpful, and you might want to design your code to
 
@@ -43,7 +43,7 @@ applications, the applications will not be truly stand-alone, as the application
 will still need the Tcl and Tk libraries.
 
 One solution is to ship the application with the Tcl and Tk libraries, and point
-to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
+to them at run-time using the :envvar:`!TCL_LIBRARY` and :envvar:`!TK_LIBRARY`
 environment variables.
 
 Various third-party freeze libraries such as py2exe and cx_Freeze have
@@ -55,16 +55,17 @@ Can I have Tk events handled while waiting for I/O?
 
 On platforms other than Windows, yes, and you don't even
 need threads!  But you'll have to restructure your I/O
-code a bit.  Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
+code a bit.  Tk has the equivalent of Xt's :c:func:`!XtAddInput` call, which allows you
 to register a callback function which will be called from the Tk mainloop when
 I/O is possible on a file descriptor.  See :ref:`tkinter-file-handlers`.
 
 
 I can't get key bindings to work in Tkinter: why?
 -------------------------------------------------
 
-An often-heard complaint is that event handlers bound to events with the
-:meth:`bind` method don't get handled even when the appropriate key is pressed.
+An often-heard complaint is that event handlers :ref:`bound <bindings-and-events>`
+to events with the :meth:`!bind` method
+don't get handled even when the appropriate key is pressed.
 
 The most common cause is that the widget to which the binding applies doesn't
 have "keyboard focus".  Check out the Tk documentation for the focus command.
 
@@ -111,7 +111,7 @@ Is there an equivalent to C's onexit() in Python?
 -------------------------------------------------
 
 The :mod:`atexit` module provides a register function that is similar to C's
-:c:func:`onexit`.
+:c:func:`!onexit`.
 
 
 Why don't my signal handlers work?
@@ -397,7 +397,7 @@ These aren't::
    D[x] = D[x] + 1
 
 Operations that replace other objects may invoke those other objects'
-:meth:`__del__` method when their reference count reaches zero, and that can
+:meth:`~object.__del__` method when their reference count reaches zero, and that can
 affect things.  This is especially true for the mass updates to dictionaries and
 lists.  When in doubt, use a mutex!
 
@@ -730,14 +730,17 @@ The :mod:`select` module is commonly used to help with asynchronous I/O on
 sockets.
 
 To prevent the TCP connect from blocking, you can set the socket to non-blocking
-mode.  Then when you do the :meth:`socket.connect`, you will either connect immediately
+mode.  Then when you do the :meth:`~socket.socket.connect`,
+you will either connect immediately
 (unlikely) or get an exception that contains the error number as ``.errno``.
 ``errno.EINPROGRESS`` indicates that the connection is in progress, but hasn't
 finished yet.  Different OSes will return different values, so you're going to
 have to check what's returned on your system.
 
-You can use the :meth:`socket.connect_ex` method to avoid creating an exception.  It will
-just return the errno value.  To poll, you can call :meth:`socket.connect_ex` again later
+You can use the :meth:`~socket.socket.connect_ex` method
+to avoid creating an exception.
+To poll, you can call :meth:`~socket.socket.connect_ex` again later
 -- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
 socket to :meth:`select.select` to check if it's writable.
 
 
@@ -454,7 +454,7 @@ There are two factors that produce this result:
    (the list), and both ``x`` and ``y`` refer to it.
 2) Lists are :term:`mutable`, which means that you can change their content.
 
-After the call to :meth:`~list.append`, the content of the mutable object has
+After the call to :meth:`!append`, the content of the mutable object has
 changed from ``[]`` to ``[10]``.  Since both the variables refer to the same
 object, using either name accesses the modified value ``[10]``.
 
@@ -1397,7 +1397,7 @@ To see why this happens, you need to know that (a) if an object implements an
 :meth:`~object.__iadd__` magic method, it gets called when the ``+=`` augmented
 assignment
 is executed, and its return value is what gets used in the assignment statement;
-and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`~list.extend` on the list
+and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`!extend` on the list
 and returning the list.  That's why we say that for lists, ``+=`` is a
 "shorthand" for :meth:`!list.extend`::
 
@@ -1903,7 +1903,7 @@ identity tests.  This prevents the code from being confused by objects such as
 ``float('NaN')`` that are not equal to themselves.
 
 For example, here is the implementation of
-:meth:`collections.abc.Sequence.__contains__`::
+:meth:`!collections.abc.Sequence.__contains__`::
 
     def __contains__(self, value):
         for v in self: