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

Skip to content

Commit f82cab9

Browse files
nedbatnedbat
committed
[3.15] 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 871bd46 commit f82cab9

24 files changed

Lines changed: 157 additions & 69 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
@@ -44,6 +44,7 @@
4444
'sphinx_linklint.ext',
4545
'notfound.extension',
4646
'sphinxext.opengraph',
47+
'sphinxext.rediraffe',
4748
'sphinxcontrib.rsvgconverter',
4849
)
4950
for optional_ext in _OPTIONAL_EXTENSIONS:
@@ -361,7 +362,13 @@
361362
# Grouping the document tree into LaTeX files. List of tuples
362363
# (source start file, target name, title, author, document class [howto/manual]).
363364
latex_documents = [
364-
('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'),
365+
(
366+
'c-api/index',
367+
'c-api.tex',
368+
'The Python/C API',
369+
_doc_authors,
370+
'manual',
371+
),
365372
(
366373
'extending/index',
367374
'extending.tex',
@@ -376,6 +383,13 @@
376383
_doc_authors,
377384
'manual',
378385
),
386+
(
387+
'builtins/index',
388+
'builtins.tex',
389+
'Python Built-ins Reference',
390+
_doc_authors,
391+
'manual',
392+
),
379393
(
380394
'library/index',
381395
'library.tex',
@@ -608,3 +622,16 @@
608622
'<meta property="og:image:width" content="200">',
609623
'<meta property="og:image:height" content="200">',
610624
)
625+
626+
# Options for sphinxext-rediraffe
627+
# -------------------------------
628+
629+
rediraffe_redirects = {
630+
# Splitting builtins from library
631+
"library/functions.rst": "builtins/functions.rst",
632+
"library/stdtypes.rst": "builtins/stdtypes.rst",
633+
"library/constants.rst": "builtins/constants.rst",
634+
"library/exceptions.rst": "builtins/exceptions.rst",
635+
"library/threadsafety.rst": "builtins/threadsafety.rst",
636+
"library/time-complexity.rst": "builtins/time-complexity.rst",
637+
}

‎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: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,10 @@ underlying operating system supports this feature.
1616

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

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

0 commit comments

Comments
 (0)