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 #34316866 | 📁 Comparing 7bcbd5e against main (852381e)

  🔍 Preview build  

14 files changed · + 1 added · ± 13 modified

+ Added

• library/builtin-index.html

± Modified

• glossary.html
• index.html
• extending/index.html
• faq/general.html
• library/ast.html
• library/index.html
• library/intro.html
• reference/index.html
• reference/introduction.html
• tutorial/index.html
• and 3 more...

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

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