Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 8b2dd80

Browse files
nedbatnedbat
authored
[3.13] Docs: split builtins to their own page from library (GH-156682) (#157440)
* [3.13] Docs: split builtins to their own page from library (GH-156682) * Docs: split builtins to their own page from library * review feedback * addressed Hugo's feedback * update the What's Next page * one more wording tweak * move builtins to their own directory. fix the reference name * moved pages need to be noted in tools/removed-ids.txt * add Python to the builtins reference title * add sphinxext-rediraffe for the library->builtins split * update check-html-ids to handle rediraffe redirects * now we don't need (page missing) for the redirected pages * update other references to moved pages * A seealso from builtins to library * make a nice section for rediraffe settings * move the builtins note to the end, as a seealso * address merwok's comments * cache looking for ids in files * simplify the intro paragraphs (cherry picked from commit 59c4bdd) Co-authored-by: Ned Batchelder <[email protected]> * remove references to non-existent pages
1 parent 50f66bf commit 8b2dd80

17 files changed

Lines changed: 113 additions & 62 deletions

File tree

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

File renamed without changes.

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

File renamed without changes.

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

File renamed without changes.

‎Doc/builtins/index.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. _builtins-index:
2+
3+
##############################
4+
Python built-ins reference
5+
##############################
6+
7+
Python comes with a number of built-in functions and classes.
8+
9+
The built-in classes include data types that would normally be considered part
10+
of the "core" of a language, such as numbers and lists. For these types, the
11+
Python language core defines the form of literals and places some constraints
12+
on their semantics, but does not fully define the semantics.
13+
14+
The built-ins also include functions and exceptions --- objects that can
15+
be used by all Python code without the need of an :keyword:`import` statement.
16+
Some of these are defined by the core language, but many are not essential for
17+
the core semantics and are only described here.
18+
19+
.. seealso::
20+
21+
In addition to the built-ins, Python provides an extensive importable
22+
standard library, see :ref:`library-index`.
23+
24+
.. We don't use :numbered: option for the TOC below as it enforces
25+
numbered sections for the entire builtin docs. If desired,
26+
:numbered: can be enabled on a per-page basis.
27+
.. toctree::
28+
:maxdepth: 2
29+
30+
stdtypes.rst
31+
constants.rst
32+
functions.rst
33+
exceptions.rst

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

File renamed without changes.

‎Doc/conf.py‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@
4242
'sphinx_linklint.ext',
4343
'notfound.extension',
4444
'sphinxext.opengraph',
45+
'sphinxext.rediraffe',
46+
'sphinxcontrib.rsvgconverter',
4547
)
4648
for optional_ext in _OPTIONAL_EXTENSIONS:
4749
try:
@@ -356,7 +358,13 @@
356358
# Grouping the document tree into LaTeX files. List of tuples
357359
# (source start file, target name, title, author, document class [howto/manual]).
358360
latex_documents = [
359-
('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'),
361+
(
362+
'c-api/index',
363+
'c-api.tex',
364+
'The Python/C API',
365+
_doc_authors,
366+
'manual',
367+
),
360368
(
361369
'extending/index',
362370
'extending.tex',
@@ -371,6 +379,13 @@
371379
_doc_authors,
372380
'manual',
373381
),
382+
(
383+
'builtins/index',
384+
'builtins.tex',
385+
'Python Built-ins Reference',
386+
_doc_authors,
387+
'manual',
388+
),
374389
(
375390
'library/index',
376391
'library.tex',
@@ -597,3 +612,14 @@
597612
'<meta property="og:image:width" content="200">',
598613
'<meta property="og:image:height" content="200">',
599614
)
615+
616+
# Options for sphinxext-rediraffe
617+
# -------------------------------
618+
619+
rediraffe_redirects = {
620+
# Splitting builtins from library
621+
"library/functions.rst": "builtins/functions.rst",
622+
"library/stdtypes.rst": "builtins/stdtypes.rst",
623+
"library/constants.rst": "builtins/constants.rst",
624+
"library/exceptions.rst": "builtins/exceptions.rst",
625+
}

‎Doc/contents.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
tutorial/index.rst
99
using/index.rst
1010
reference/index.rst
11+
builtins/index.rst
1112
library/index.rst
1213
extending/index.rst
1314
c-api/index.rst

‎Doc/extending/index.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,12 @@ language. Finally, it shows how to compile and link extension modules so that
1212
they can be loaded dynamically (at run time) into the interpreter, if the
1313
underlying operating system supports this feature.
1414

15-
This document assumes basic knowledge about Python. For an informal
16-
introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index`
17-
gives a more formal definition of the language. :ref:`library-index` documents
18-
the existing object types, functions and modules (both built-in and written in
19-
Python) that give the language its wide application range.
15+
This document assumes basic knowledge about C and Python. For an informal
16+
introduction to Python, see :ref:`tutorial-index`. :ref:`reference-index`
17+
gives a more formal definition of the language. :ref:`builtins-index` documents
18+
the built-in functions and object types, and :ref:`library-index` documents the
19+
modules (both built-in and written in Python) that give the language its wide
20+
application range.
2021

2122
For a detailed description of the whole Python/C API, see the separate
2223
:ref:`c-api-index`.

‎Doc/library/index.rst‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
.. _library-index:
22

33
###############################
4-
The Python Standard Library
4+
The Python standard library
55
###############################
66

7-
While :ref:`reference-index` describes the exact syntax and
8-
semantics of the Python language, this library reference manual
9-
describes the standard library that is distributed with Python. It also
10-
describes some of the optional components that are commonly included
11-
in Python distributions.
7+
This library reference manual describes the standard library
8+
distributed with Python. It also describes some of the optional
9+
components that are commonly included in Python distributions.
1210

13-
Python's standard library is very extensive, offering a wide range of
11+
Elsewhere, :ref:`reference-index` describes the exact syntax and
12+
semantics of the Python language, and :ref:`builtins-index` describes
13+
the built-in functions.
14+
15+
Python's standard library is extensive, offering a wide range of
1416
facilities as indicated by the long table of contents listed below. The
1517
library contains built-in modules (written in C) that provide access to
1618
system functionality such as file I/O that would otherwise be
@@ -39,11 +41,6 @@ the `Python Package Index <https://pypi.org>`_.
3941
:maxdepth: 2
4042

4143
intro.rst
42-
functions.rst
43-
constants.rst
44-
stdtypes.rst
45-
exceptions.rst
46-
4744
text.rst
4845
binary.rst
4946
datatypes.rst

‎Doc/library/intro.rst‎

Lines changed: 15 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,48 +4,34 @@
44
Introduction
55
************
66

7-
The "Python library" contains several different kinds of components.
8-
9-
It contains data types that would normally be considered part of the "core" of a
10-
language, such as numbers and lists. For these types, the Python language core
11-
defines the form of literals and places some constraints on their semantics, but
12-
does not fully define the semantics. (On the other hand, the language core does
13-
define syntactic properties like the spelling and priorities of operators.)
14-
15-
The library also contains built-in functions and exceptions --- objects that can
16-
be used by all Python code without the need of an :keyword:`import` statement.
17-
Some of these are defined by the core language, but many are not essential for
18-
the core semantics and are only described here.
19-
20-
The bulk of the library, however, consists of a collection of modules. There are
21-
many ways to dissect this collection. Some modules are written in C and built
22-
in to the Python interpreter; others are written in Python and imported in
23-
source form. Some modules provide interfaces that are highly specific to
7+
The Python standard library consists of a collection of modules. There are
8+
many ways to dissect this collection. Most modules are written in Python,
9+
but some are written in C. All can be imported into your program to add
10+
functionality. Some modules provide interfaces that are highly specific to
2411
Python, like printing a stack trace; some provide interfaces that are specific
2512
to particular operating systems, such as access to specific hardware; others
2613
provide interfaces that are specific to a particular application domain, like
27-
the World Wide Web. Some modules are available in all versions and ports of
14+
web development. Some modules are available in all versions and ports of
2815
Python; others are only available when the underlying system supports or
2916
requires them; yet others are available only when a particular configuration
3017
option was chosen at the time when Python was compiled and installed.
3118

32-
This manual is organized "from the inside out:" it first describes the built-in
33-
functions, data types and exceptions, and finally the modules, grouped in
34-
chapters of related modules.
35-
36-
This means that if you start reading this manual from the start, and skip to the
19+
If you start reading this manual from the start, and skip to the
3720
next chapter when you get bored, you will get a reasonable overview of the
3821
available modules and application areas that are supported by the Python
3922
library. Of course, you don't *have* to read it like a novel --- you can also
4023
browse the table of contents (in front of the manual), or look for a specific
4124
function, module or term in the index (in the back). And finally, if you enjoy
42-
learning about random subjects, you choose a random page number (see module
43-
:mod:`random`) and read a section or two. Regardless of the order in which you
44-
read the sections of this manual, it helps to start with chapter
45-
:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with
46-
this material.
25+
learning about random subjects, you choose a random page
26+
and read a section or two. Regardless of the order in which you
27+
read the sections of this manual, it helps to first read
28+
:ref:`built-in-funcs`, as the remainder of this section
29+
assumes familiarity with this material.
30+
31+
.. seealso::
4732

48-
Let the show begin!
33+
The built-in functions and classes (which can be used without an
34+
:keyword:`import` statement) are described in :ref:`builtins-index`.
4935

5036

5137
.. _availability:

0 commit comments

Comments
 (0)