[3.15] Docs: split builtins to their own page from library (GH-156682) (#157442)

Author: nedbat

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

@@ -0,0 +1,35 @@
+.. _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
+   threadsafety.rst
+   time-complexity.rst

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

@@ -44,6 +44,7 @@
     'sphinx_linklint.ext',
     'notfound.extension',
     'sphinxext.opengraph',
+    'sphinxext.rediraffe',
     'sphinxcontrib.rsvgconverter',
 )
 for optional_ext in _OPTIONAL_EXTENSIONS:
@@ -361,7 +362,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',
@@ -376,6 +383,13 @@
         _doc_authors,
         'manual',
     ),
+    (
+        'builtins/index',
+        'builtins.tex',
+        'Python Built-ins Reference',
+        _doc_authors,
+        'manual',
+    ),
     (
         'library/index',
         'library.tex',
@@ -608,3 +622,16 @@
         '<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",
+    "library/threadsafety.rst": "builtins/threadsafety.rst",
+    "library/time-complexity.rst": "builtins/time-complexity.rst",
+}

Doc/library/functions.rst Doc/builtins/functions.rstDoc/library/functions.rst renamed to Doc/builtins/functions.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

Doc/builtins/index.rst

@@ -16,9 +16,10 @@ underlying operating system supports this feature.
 
 This document assumes basic knowledge about C and Python.  For an informal
 introduction to Python, see :ref:`tutorial-index`.  :ref:`reference-index`
-gives a more formal definition of the language.  :ref:`library-index` documents
-the existing object types, functions and modules (both built-in and written in
-Python) that give the language its wide application range.
+gives a more formal definition of the language.  :ref:`builtins-index` documents
+the built-in functions and object types, and :ref:`library-index` documents the
+modules (both built-in and written in Python) that give the language its wide
+application range.
 
 For a detailed description of the whole Python/C API, see the separate
 :ref:`c-api-index`.