Docs: split builtins to their own page from library by nedbat · Pull Request #156682 · python/cpython · GitHub

We've talked about separating the built-ins from the stdlib modules, since "dict" (for example) isn't part of the stdlib.

I think I took care of all the places the pages are referenced, but the non-HTML builds are new to me, so I might have missed something.

I tried to make the intro paragraphs and pages useful, and avoided over-editing them.

Also: is this NEWS-worthy?

Also: is this NEWS-worthy?

I don't see a need for one here, I think the docs speak for themselves.

Documentation build overview

📚 cpython-previews | 🛠️ Build #34528081 | 📁 Comparing e02ea99 against main (852381e)

🔍 Preview build

74 files changed · + 7 added · ± 67 modified

+ Added

± Modified

Shall we name the new Doc/library/builtin-index.rst as Doc/builtins/index.rst instead?

Then instead of:

https://docs.python.org/3/library/builtins-index.html

We get a neater:

This PR can still reference the builtin stuff in their current location, and a followup could move the relevant files and deal with redirects:

Doc/library/functions.rst -> Doc/builtins/functions.rst
Doc/library/stdtypes.rst -> Doc/builtins/stdtypes.rst
Doc/library/constants.rst -> Doc/builtins/constants.rst
Doc/library/exceptions.rst -> Doc/builtins/exceptions.rst
Doc/library/threadsafety.rst -> Doc/builtins/threadsafety.rst
Doc/library/time-complexity.rst -> Doc/builtins/time-complexity.rst

Also, you need to update the What Now? page in the tutorial.

I concur with Hugo, splitting this into a separate directory would be nicer. We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

I can do the renames and redirects.

We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

What Sphinx extension have we used for redirects before? I see https://github.com/python/psf-salt/blob/main/salt/docs/config/nginx.docs-redirects.conf for the psf-salt approach.

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

I knew rediraffe was somewhere! Is there a reason we don't want to introduce it for the main docs?

Is there a reason we don't want to introduce it for the main docs?

I presume it's simply because there hasn't really been a need so far. We're less keen to move pages here than in the Devguide. IIRC rediraffe requires JS, but that ship has sailed anyway.

Server-side psf-salt redirects would be better than client-side sphinxext-rediraffe: they work with JavaScript disabled (better for all the scrapers and bots), are faster on server-side (HTTP layer before any HTML fetched), and get cached in the CDN, and better for SEO.

We don't have such server-side control for the devguide, which is hosted on GitHub Pages. (Also I'd say client-side JS redirects are fine for the less-important devguide.)

That all makes sense. Do we have a way to coordinate the updates to psf-salt with updates to the docs, especially with backports involved?

(There's no documented process I'm afraid) You can open a PR there and limit the redirect to specific Python versions. I can review and merge when we land this.

Moving pages causes the "removed HTML IDs" check to fail. The IDs aren't gone, they are in a different page. Do I still add them to removed-ids.txt?

Do I still add them to removed-ids.txt?

Yes, see the line with an asyncio file for the required format.

Merge in main to fix:

      File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.14/site-packages/sphinx/builders/changes.py", line 61, in write_documents
        ttext = self.typemap[changeset.type]
                ~~~~~~~~~~~~^^^^^^^^^^^^^^^^
    KeyError: 'soft-deprecated'

Thanks @nedbat for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

Sorry, @nedbat, I could not cleanly backport this to 3.15 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 59c4bddb1762b4706c942d6403fb8df470f37e05 3.15

Sorry, @nedbat, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 59c4bddb1762b4706c942d6403fb8df470f37e05 3.14

Sorry, @nedbat, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 59c4bddb1762b4706c942d6403fb8df470f37e05 3.13

GH-157440 is a backport of this pull request to the 3.13 branch.

GH-157441 is a backport of this pull request to the 3.14 branch.

GH-157442 is a backport of this pull request to the 3.15 branch.

#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 <ned@nedbatchelder.com> * remove references to non-existent pages

#157441) * 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)

#157442)

I've added server-side redirects in python/psf-salt#651.

* 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

nedbat requested review from AA-Turner, StanFromIreland, hugovk and willingc as code owners August 30, 2026 20:07

bedevere-app Bot added the awaiting core review label Aug 30, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 37b2ad3 to 10c84e6 Compare August 30, 2026 20:10

nedbat added the skip issue label Aug 30, 2026

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/tools/templates/indexcontent.html Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/index.rst

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

nedbat added the skip news label Aug 30, 2026

hugovk reviewed Aug 31, 2026

View reviewed changes

StanFromIreland reviewed Aug 31, 2026

View reviewed changes

Comment thread Doc/reference/index.rst Outdated

nedbat added the docs Documentation in the Doc dir label Sep 1, 2026

github-project-automation Bot added this to Docs PRs Sep 1, 2026

github-project-automation Bot moved this to Todo in Docs PRs Sep 1, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from c6de373 to ea9966e Compare September 1, 2026 17:43

Merge branch 'main' into nedbat/split-builtin-stdlib

e02ea99

StanFromIreland mentioned this pull request Sep 13, 2026

gh-59551: Add a stub page for the old library/dialog.html URL #156949

Closed

nedbat merged commit 59c4bdd into python:main Sep 13, 2026
51 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Sep 13, 2026

bedevere-app Bot removed the awaiting merge label Sep 13, 2026

miss-islington-app Bot assigned nedbat Sep 13, 2026

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Sep 13, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Sep 13, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Sep 13, 2026

hugovk pushed a commit that referenced this pull request Sep 13, 2026

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

17bbb3b

#157442)

nedbat mentioned this pull request Sep 13, 2026

Redirects for Docs #156682 python/psf-salt#651

Merged

nedbat deleted the nedbat/split-builtin-stdlib branch September 13, 2026 17:43

This was referenced Sep 18, 2026

Rename builtin functions article name python/devguide#1908

Merged

Add German language support to config.toml and language switcher python/docsbuild-scripts#355

Merged

This was referenced Oct 1, 2026

resume-from-pr: GitHub REST issue comments lose their author jonbaldie/skills#162

Closed

Page PR collections in extract-pr.py and report gaps jonbaldie/skills#163

Open

Keep REST issue comment authors in resume-from-pr briefs jonbaldie/skills#165

Merged

hugovk mentioned this pull request Oct 13, 2026

gh-138277: Elevate Built-in Types and Functions in Documentation Search #138278

Open

Docs: split builtins to their own page from library by nedbat · Pull Request #156682 · python/cpython · GitHub

Repository navigation

Docs: split builtins to their own page from library - #156682

Docs: split builtins to their own page from library#156682nedbat merged 20 commits intopython:mainpython/cpython:mainfrom nedbat:nedbat/split-builtin-stdlibnedbat/cpython:nedbat/split-builtin-stdlibCopy head branch name to clipboard

Conversation

nedbat commented Aug 30, 2026

Uh oh!

nedbat commented Aug 30, 2026

Uh oh!

StanFromIreland commented Aug 30, 2026

Uh oh!

read-the-docs-community Bot commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

hugovk commented Sep 1, 2026

Uh oh!

nedbat commented Sep 1, 2026

Uh oh!

StanFromIreland commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Sep 2, 2026

Uh oh!

StanFromIreland commented Sep 2, 2026

Uh oh!

hugovk commented Sep 12, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Sep 13, 2026

Uh oh!

miss-islington-app Bot commented Sep 13, 2026

Uh oh!

miss-islington-app Bot commented Sep 13, 2026

Uh oh!

miss-islington-app Bot commented Sep 13, 2026

Uh oh!

bedevere-app Bot commented Sep 13, 2026

Uh oh!

bedevere-app Bot commented Sep 13, 2026

Uh oh!

bedevere-app Bot commented Sep 13, 2026

Uh oh!

nedbat commented Sep 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Docs: split builtins to their own page from library#156682
nedbat merged 20 commits into
python:mainfrom
nedbat:nedbat/split-builtin-stdlib

read-the-docs-community Bot commented Aug 30, 2026 •
edited
Loading

StanFromIreland commented Sep 1, 2026 •
edited
Loading