Merge branch 'main' into frozendict_pickle

Author: vstinner

.github/CODEOWNERS

@@ -424,6 +424,7 @@ Lib/test/test_dataclasses/    @ericvsmith
 
 # Dates and times
 Doc/**/*time.rst                 @pganssle @abalkin
+Doc/library/datetime-*           @pganssle
 Doc/library/zoneinfo.rst         @pganssle
 Include/datetime.h               @pganssle @abalkin
 Include/internal/pycore_time.h   @pganssle @abalkin
@@ -473,8 +474,9 @@ Lib/test/test_functools.py    @rhettinger
 Modules/_functoolsmodule.c    @rhettinger
 
 # Garbage collector
-Modules/gcmodule.c            @pablogsal
-Doc/library/gc.rst            @pablogsal
+Modules/gcmodule.c                @pablogsal
+Doc/library/gc.rst                @pablogsal
+InternalDocs/garbage_collector.md @pablogsal
 
 # Gettext
 Doc/library/gettext.rst       @tomasr8

.github/ISSUE_TEMPLATE/documentation.yml

@@ -8,8 +8,9 @@ body:
         > [!NOTE]
         > Trivial changes (for example typos) don’t require an issue before opening a PR.
   - type: textarea
+    id: description
     attributes:
       label: "Documentation"
-      description: "A clear and concise description of the issue."
+      description: "A clear and concise description of the issue. Include a link to the page."
     validations:
       required: true

Doc/conf.py

@@ -227,10 +227,6 @@
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [
-    # 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.
-    ('py:meth', '_SubParsersAction.add_parser'),
     # Attributes/methods/etc. that definitely should be documented better,
     # but are deferred for now:
     ('py:attr', '__wrapped__'),

Doc/faq/programming.rst

@@ -1852,6 +1852,8 @@ to the object:
 13891296
 
 
+.. _faq-identity-with-is:
+
 When can I rely on identity tests with the *is* operator?
 ---------------------------------------------------------
 

Doc/improve-page-nojs.rst

@@ -0,0 +1,29 @@
+:orphan:
+
+****************************
+Improve a documentation page
+****************************
+
+.. This is the no-javascript version of this page. The one most people
+   will see (with JavaScript enabled) is improve-page.rst. If you edit
+   this page, please also edit that one, and vice versa.
+
+.. only:: html and not epub
+
+We are always interested to hear ideas about improvements to the documentation.
+
+.. only:: translation
+
+   If the bug or suggested improvement concerns the translation of this
+   documentation, open an issue or edit the page in
+   `translation's repository <TRANSLATION_REPO_>`_ instead.
+
+You have a few ways to ask questions or suggest changes:
+
+- You can start a discussion about the page on the Python discussion forum.
+  This link will start a topic in the Documentation category:
+  `New Documentation topic <https://discuss.python.org/new-topic?category=documentation>`_.
+
+- You can open an issue on the Python GitHub issue tracker. This link will
+  create a new issue with the "docs" label:
+  `New docs issue <https://github.com/python/cpython/issues/new?template=documentation.yml>`_.

Doc/improve-page.rst

@@ -0,0 +1,65 @@
+:orphan:
+
+****************************
+Improve a documentation page
+****************************
+
+.. This is the JavaScript-enabled version of this page. Another version
+   (for those with JavaScript disabled) is improve-page-nojs.rst. If you
+   edit this page, please also edit that one, and vice versa.
+
+.. only:: html and not epub
+
+   .. raw:: html
+
+      <script>
+         function applyReplacements(text, params) {
+            return text
+               .replace(/PAGETITLE/g, params.get('pagetitle'))
+               .replace(/PAGEURL/g, params.get('pageurl'))
+               .replace(/PAGESOURCE/g, params.get('pagesource'));
+         }
+
+         document.addEventListener('DOMContentLoaded', () => {
+            const params = new URLSearchParams(window.location.search);
+            const walker = document.createTreeWalker(
+               document.body,
+               NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+               null
+            );
+
+            while (walker.nextNode()) {
+               const node = walker.currentNode;
+
+               if (node.nodeType === Node.TEXT_NODE) {
+                  node.textContent = applyReplacements(node.textContent, params)
+               } else if (node.nodeName === 'A' && node.href) {
+                  node.setAttribute('href', applyReplacements(node.getAttribute('href'), params));
+               }
+            }
+         });
+      </script>
+
+We are always interested to hear ideas about improvements to the documentation.
+
+You were reading "PAGETITLE" at `<PAGEURL>`_.  The source for that page is on
+`GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_.
+
+.. only:: translation
+
+   If the bug or suggested improvement concerns the translation of this
+   documentation, open an issue or edit the page in
+   `translation's repository <TRANSLATION_REPO_>`_ instead.
+
+You have a few ways to ask questions or suggest changes:
+
+- You can start a discussion about the page on the Python discussion forum.
+  This link will start a pre-populated topic:
+  `Question about page "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+page+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_.
+
+- You can open an issue on the Python GitHub issue tracker. This link will
+  create a new pre-populated issue:
+  `Docs: problem with page "PAGETITLE" <https://github.com/python/cpython/issues/new?template=documentation.yml&title=Docs%3A+problem+with+page+%22PAGETITLE%22&description=The+page+at+PAGEURL+has+a+problem%3A>`_.
+
+- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_
+  to open a pull request and begin the contribution process.

Doc/library/datetime-inheritance.dot

@@ -0,0 +1,31 @@
+// Used to generate datetime-inheritance.svg with Graphviz
+// (https://graphviz.org/) for the datetime documentation.
+
+digraph {
+    comment="Generated with datetime-inheritance.dot"
+    graph [
+        bgcolor="transparent"
+        fontnames="svg"
+        layout="dot"
+        ranksep=0.5
+        nodesep=0.5
+        splines=line
+    ]
+    node [
+        fontname="Courier"
+        fontsize=14.0
+        shape=box
+        style=rounded
+        margin="0.15,0.07"
+    ]
+    edge [
+        arrowhead=none
+    ]
+
+    object -> tzinfo
+    object -> timedelta
+    object -> time
+    object -> date
+    tzinfo -> timezone
+    date -> datetime
+}