Merge branch '3.13' into backport-1b424c0-3.13

Author: encukou

.github/workflows/reusable-docs.yml

@@ -86,6 +86,9 @@ jobs:
           --fail-if-regression \
           --fail-if-improved \
           --fail-if-new-news-nit
+    - name: 'Build list of changes'
+      run: |
+        make -C Doc/ PYTHON=../python changes
 
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:

Doc/library/constants.rst Doc/builtins/constants.rstDoc/library/constants.rst renamed to Doc/builtins/constants.rst

@@ -0,0 +1,33 @@
+.. _builtins-index:
+
+##############################
+  Python built-ins reference
+##############################
+
+Python comes with a number of built-in functions and classes.
+
+The built-in classes include data types that would normally be considered part
+of the "core" of a language, such as numbers and lists.  For these types, the
+Python language core defines the form of literals and places some constraints
+on their semantics, but does not fully define the semantics.
+
+The built-ins also include functions and exceptions --- objects that can
+be used by all Python code without the need of an :keyword:`import` statement.
+Some of these are defined by the core language, but many are not essential for
+the core semantics and are only described here.
+
+.. seealso::
+
+   In addition to the built-ins, Python provides an extensive importable
+   standard library, see :ref:`library-index`.
+
+.. We don't use :numbered: option for the TOC below as it enforces
+   numbered sections for the entire builtin docs.  If desired,
+   :numbered: can be enabled on a per-page basis.
+.. toctree::
+   :maxdepth: 2
+
+   stdtypes.rst
+   constants.rst
+   functions.rst
+   exceptions.rst

Doc/library/exceptions.rst Doc/builtins/exceptions.rstDoc/library/exceptions.rst renamed to Doc/builtins/exceptions.rst

@@ -12,6 +12,12 @@ Byte Array Objects
 
    This subtype of :c:type:`PyObject` represents a Python bytearray object.
 
+   .. impl-detail::
+
+      The internal buffer of :c:type:`PyByteArrayObject` always includes an
+      extra trailing null byte for compatibility with null terminated C
+      strings.  This extra byte is not counted in :c:func:`PyByteArray_Size`
+      nor in the *len* arguments of the functions below.
 
 .. c:var:: PyTypeObject PyByteArray_Type
 

Doc/library/functions.rst Doc/builtins/functions.rstDoc/library/functions.rst renamed to Doc/builtins/functions.rst

@@ -8,6 +8,13 @@ Bytes Objects
 These functions raise :exc:`TypeError` when expecting a bytes parameter and
 called with a non-bytes parameter.
 
+.. impl-detail::
+
+   The internal buffer of :c:type:`PyBytesObject` always includes an extra
+   trailing null byte for compatibility with null terminated C strings.
+   This extra byte is not counted in :c:func:`PyBytes_Size` nor in the
+   various *length* and *size* arguments of the functions below.
+
 .. index:: pair: object; bytes
 
 

Doc/builtins/index.rst

@@ -42,6 +42,8 @@
     'sphinx_linklint.ext',
     'notfound.extension',
     'sphinxext.opengraph',
+    'sphinxext.rediraffe',
+    'sphinxcontrib.rsvgconverter',
 )
 for optional_ext in _OPTIONAL_EXTENSIONS:
     try:
@@ -74,6 +76,8 @@
 # and replace the values accordingly.
 # See Doc/tools/extensions/patchlevel.py
 version, release = get_version_info()
+v = get_header_version_info()
+branch = "main" if v.releaselevel == "alpha" else f"{v.major}.{v.minor}"
 
 rst_epilog = f"""
 .. |python_version_literal| replace:: ``Python {version}``
@@ -292,6 +296,7 @@
     "repository_url": repository_url or None,
     "pr_id": os.getenv("READTHEDOCS_VERSION"),
     "enable_analytics": os.getenv("PYTHON_DOCS_ENABLE_ANALYTICS"),
+    "source_branch": branch,
 }
 
 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
@@ -301,6 +306,9 @@
 # Path to find HTML templates to override theme
 templates_path = ['tools/templates']
 
+# We link to sources on GitHub, so don't copy them into the HTML output.
+html_copy_source = False
+
 # Custom sidebar templates, filenames relative to this file.
 html_sidebars = {
     # Defaults taken from https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
@@ -356,7 +364,13 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
-    ('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'),
+    (
+        'c-api/index',
+        'c-api.tex',
+        'The Python/C API',
+        _doc_authors,
+        'manual',
+    ),
     (
         'extending/index',
         'extending.tex',
@@ -371,6 +385,13 @@
         _doc_authors,
         'manual',
     ),
+    (
+        'builtins/index',
+        'builtins.tex',
+        'Python Built-ins Reference',
+        _doc_authors,
+        'manual',
+    ),
     (
         'library/index',
         'library.tex',
@@ -549,9 +570,6 @@
 # Options for sphinx.ext.extlinks
 # -------------------------------
 
-v = get_header_version_info()
-branch = "main" if v.releaselevel == "alpha" else f"{v.major}.{v.minor}"
-
 # This config is a dictionary of external sites,
 # mapping unique short aliases to a base URL and a prefix.
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
@@ -597,3 +615,14 @@
         '<meta property="og:image:width" content="200">',
         '<meta property="og:image:height" content="200">',
     )
+
+# Options for sphinxext-rediraffe
+# -------------------------------
+
+rediraffe_redirects = {
+    # Splitting builtins from library
+    "library/functions.rst": "builtins/functions.rst",
+    "library/stdtypes.rst": "builtins/stdtypes.rst",
+    "library/constants.rst": "builtins/constants.rst",
+    "library/exceptions.rst": "builtins/exceptions.rst",
+}

Doc/library/stdtypes.rst Doc/builtins/stdtypes.rstDoc/library/stdtypes.rst renamed to Doc/builtins/stdtypes.rst

@@ -8,6 +8,7 @@
    tutorial/index.rst
    using/index.rst
    reference/index.rst
+   builtins/index.rst
    library/index.rst
    extending/index.rst
    c-api/index.rst