Docs: split builtins to their own page from library

Author: nedbat

Doc/conf.py

@@ -359,7 +359,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',
@@ -374,6 +380,13 @@
         _doc_authors,
         'manual',
     ),
+    (
+        'library/builtin-index',
+        'builtin.tex',
+        'Built-in Functions and Classes',
+        _doc_authors,
+        'manual',
+    ),
     (
         'library/index',
         'library.tex',

Doc/contents.rst

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

Doc/extending/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:`builtin-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`.

Doc/library/builtin-index.rst

@@ -0,0 +1,30 @@
+.. _builtin-index:
+
+##################################
+  Built-in Functions and Classes
+##################################
+
+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 includes 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.
+
+.. We don't use :numbered: option for the TOC below as it enforces
+   numbered sections for the entire stdlib docs.  If desired,
+   :numbered: can be enabled on a per-module basis.
+.. toctree::
+   :maxdepth: 2
+
+   functions.rst
+   constants.rst
+   stdtypes.rst
+   exceptions.rst
+   threadsafety.rst
+   time-complexity.rst

Doc/library/index.rst

@@ -39,12 +39,6 @@ the `Python Package Index <https://pypi.org>`_.
    :maxdepth: 2
 
    intro.rst
-   functions.rst
-   constants.rst
-   stdtypes.rst
-   exceptions.rst
-   threadsafety.rst
-   time-complexity.rst
 
    text.rst
    binary.rst

Doc/library/intro.rst

@@ -4,43 +4,29 @@
 Introduction
 ************
 
-The "Python library" contains several different kinds of components.
-
-It contains 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.  (On the other hand, the language core does
-define syntactic properties like the spelling and priorities of operators.)
-
-The library also contains built-in 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.
-
-The bulk of the library, however, consists of a collection of modules. There are
-many ways to dissect this collection.  Some modules are written in C and built
-in to the Python interpreter; others are written in Python and imported in
+Note: the built-in functions and classes (which can be used without an
+:keyword:`import` statement) are described in :ref:`builtin-index`.
+
+The Python standard library consists of a collection of modules. There are
+many ways to dissect this collection.  Some modules are written in C and compiled
+into the Python interpreter; others are written in Python and imported in
 source form.  Some modules provide interfaces that are highly specific to
 Python, like printing a stack trace; some provide interfaces that are specific
 to particular operating systems, such as access to specific hardware; others
 provide interfaces that are specific to a particular application domain, like
-the World Wide Web. Some modules are available in all versions and ports of
+the web development. Some modules are available in all versions and ports of
 Python; others are only available when the underlying system supports or
 requires them; yet others are available only when a particular configuration
 option was chosen at the time when Python was compiled and installed.
 
-This manual is organized "from the inside out:" it first describes the built-in
-functions, data types and exceptions, and finally the modules, grouped in
-chapters of related modules.
-
-This means that if you start reading this manual from the start, and skip to the
+If you start reading this manual from the start, and skip to the
 next chapter when you get bored, you will get a reasonable overview of the
 available modules and application areas that are supported by the Python
 library.  Of course, you don't *have* to read it like a novel --- you can also
 browse the table of contents (in front of the manual), or look for a specific
 function, module or term in the index (in the back).  And finally, if you enjoy
-learning about random subjects, you choose a random page number (see module
-:mod:`random`) and read a section or two.  Regardless of the order in which you
+learning about random subjects, you choose a random page
+and read a section or two.  Regardless of the order in which you
 read the sections of this manual, it helps to start with chapter
 :ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with
 this material.

Doc/reference/index.rst

@@ -4,10 +4,11 @@
   The Python Language Reference
 #################################
 
-This reference manual describes the syntax and "core semantics" of the
+This reference manual describes the syntax and core semantics of the
 language. It is terse, but attempts to be exact and complete. The semantics of
-non-essential built-in object types and of the built-in functions and modules
-are described in :ref:`library-index`. For an informal introduction to the
+built-in object types and of the built-in functions and modules
+are described in :ref:`builtin-index` and :ref:`library-index`.
+For an informal introduction to the
 language, see :ref:`tutorial-index`. For C or C++ programmers, two additional
 manuals exist: :ref:`extending-index` describes the high-level picture of how to
 write a Python extension module, and the :ref:`c-api-index` describes the

Doc/tools/templates/indexcontent.html

@@ -56,16 +56,18 @@ <h1>{{ docstitle|e }}</h1>
          <span class="linkdescr"> {% trans whatsnew_index=pathto("whatsnew/index") %}Or <a href="{{ whatsnew_index }}">all "What's new" documents since Python 2.0</a>{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{% trans %}Tutorial{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Start here: a tour of Python's syntax and features{% endtrans %}</span></li>
+      <li class="biglink"><a class="biglink" href="{{ pathto("library/builtin-index") }}">{% trans %}Built-in reference{% endtrans %}</a><br>
+         <span class="linkdescr">{% trans %}Built-in functions and classes{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">{% trans %}Library reference{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Standard library and builtins{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">{% trans %}Language reference{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Syntax and language elements{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">{% trans %}Python setup and usage{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}How to install, configure, and use Python{% endtrans %}</span></li>
-      <li class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br>
-         <span class="linkdescr">{% trans %}In-depth topic manuals{% endtrans %}</span></li>
     </ul>
     <ul>
+      <li class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br>
+         <span class="linkdescr">{% trans %}In-depth topic manuals{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python modules{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Third-party modules and PyPI.org{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and embedding{% endtrans %}</a><br>

Doc/tutorial/index.rst

@@ -30,9 +30,9 @@ have a basic understanding of programming in general. It helps to have a Python
 interpreter handy for hands-on experience, but all examples are self-contained,
 so the tutorial can be read off-line as well.
 
-For a description of standard objects and modules, see :ref:`library-index`.
-:ref:`reference-index` gives a more formal definition of the language.  To write
-extensions in C or C++, read :ref:`extending-index` and
+For a description of standard objects and modules, see :ref:`builtin-index` and
+:ref:`library-index`.  :ref:`reference-index` gives a more formal definition of
+the language.  To write extensions in C or C++, read :ref:`extending-index` and
 :ref:`c-api-index`. There are also several books covering Python in depth.
 
 This tutorial does not attempt to be comprehensive and cover every single