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

Skip to content

Commit 593fec9

Browse files
nedbatnedbat
committed
[3.14] 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]>
1 parent c348765 commit 593fec9

22 files changed

Lines changed: 157 additions & 68 deletions

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: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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
34+
threadsafety.rst
35+
time-complexity.rst

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

File renamed without changes.

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

File renamed without changes.

Doc/library/time-complexity.rst renamed to Doc/builtins/time-complexity.rst

File renamed without changes.

‎Doc/conf.py‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
'sphinx_linklint.ext',
4444
'notfound.extension',
4545
'sphinxext.opengraph',
46+
'sphinxext.rediraffe',
4647
'sphinxcontrib.rsvgconverter',
4748
)
4849
for optional_ext in _OPTIONAL_EXTENSIONS:
@@ -364,7 +365,13 @@
364365
# Grouping the document tree into LaTeX files. List of tuples
365366
# (source start file, target name, title, author, document class [howto/manual]).
366367
latex_documents = [
367-
('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'),
368+
(
369+
'c-api/index',
370+
'c-api.tex',
371+
'The Python/C API',
372+
_doc_authors,
373+
'manual',
374+
),
368375
(
369376
'extending/index',
370377
'extending.tex',
@@ -379,6 +386,13 @@
379386
_doc_authors,
380387
'manual',
381388
),
389+
(
390+
'builtins/index',
391+
'builtins.tex',
392+
'Python Built-ins Reference',
393+
_doc_authors,
394+
'manual',
395+
),
382396
(
383397
'library/index',
384398
'library.tex',
@@ -606,3 +620,16 @@
606620
'<meta property="og:image:width" content="200">',
607621
'<meta property="og:image:height" content="200">',
608622
)
623+
624+
# Options for sphinxext-rediraffe
625+
# -------------------------------
626+
627+
rediraffe_redirects = {
628+
# Splitting builtins from library
629+
"library/functions.rst": "builtins/functions.rst",
630+
"library/stdtypes.rst": "builtins/stdtypes.rst",
631+
"library/constants.rst": "builtins/constants.rst",
632+
"library/exceptions.rst": "builtins/exceptions.rst",
633+
"library/threadsafety.rst": "builtins/threadsafety.rst",
634+
"library/time-complexity.rst": "builtins/time-complexity.rst",
635+
}

‎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`.

0 commit comments

Comments
 (0)