Docs: split builtins to their own page from library

[nedbat]

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.

[nedbat]

Also: is this NEWS-worthy?

[StanFromIreland]

Also: is this NEWS-worthy?

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

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34356185 | 📁 Comparing 96bad77 against main (852381e)

  🔍 Preview build  

31 files changed · + 7 added · ± 18 modified · - 6 deleted

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html

± Modified

• glossary.html
• index.html
• extending/index.html
• faq/general.html
• library/ast.html
• library/concurrent.interpreters.html
• library/index.html
• library/intro.html
• library/tomllib.html
• library/xml.etree.elementtree.html
• and 8 more...

- Deleted

• library/constants.html
• library/exceptions.html
• library/functions.html
• library/stdtypes.html
• library/threadsafety.html
• library/time-complexity.html

[hugovk]

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:

• https://docs.python.org/3/builtins/index.html
• aka https://docs.python.org/3/builtins/

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

[StanFromIreland]

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).

[StanFromIreland]

I don't think we should drop "non-essential" what about everything documented in the datamodel?

[nedbat]

I didn't see what the word "non-essential" was adding here. Which built-in object types are non-essential?

[StanFromIreland]

Types like range, which aren't documented in the Data model.

[encukou]

+1 for removing the word now.

IMO, Data Model contains largely duplicate information; the relevant parts of it should be moved to builtins/ (just like this PR moves library/, except it'll need merging prose rather than moving pages).

[nedbat]

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.

[StanFromIreland]

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.

[nedbat]

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?

[StanFromIreland]

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.

[hugovk]

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.)

[nedbat]

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?

[StanFromIreland]

(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.

[nedbat]

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?

[StanFromIreland]

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

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

[encukou]

Server-side psf-salt redirects would be better than client-side sphinxext-rediraffe

Why not both?

Rediraffe would work when the docs are hosted elsewhere. Also, it would be good if the official list of redirects stays together with the rest of the docs (not only to integrate it with the removed-ids.txt checker).

[encukou]

+1 for removing the word now.

IMO, Data Model contains largely duplicate information; the relevant parts of it should be moved to builtins/ (just like this PR moves library/, except it'll need merging prose rather than moving pages).