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 #34500006 | 📁 Comparing 016ce6b against main (852381e)

  🔍 Preview build  

72 files changed · + 7 added · ± 65 modified

+ 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
• c-api/marshal.html
• c-api/module.html
• c-api/type.html
• c-api/typeobj.html
• extending/index.html
• faq/general.html
• howto/curses.html
• howto/functional.html
• and 55 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).

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

[nedbat]

Added sphinxext-rediraffe.

[nedbat]

Now the missing ids check is complaining individually about every id in the six library pages I moved. :(

[nedbat]

Ah, because rediraffe leaves library/stdtypes.html behind to actively redirect, and that file has none of the ids. Looking into updating the id checker.

[nedbat]

I've updated the id checker to follow redirect files.

[nedbat]

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

BTW, the rediraffe stubs do not depend on JavaScript, it uses two techniques:

<html>
    <head>
        <noscript>
            <meta http-equiv="refresh" content="0; url=../builtins/stdtypes.html"/>
        </noscript>
    </head>
    <body>
        <script>
            window.location.href = '../builtins/stdtypes.html' + (window.location.search || '') + (window.location.hash || '');
        </script>
        <p>You should have been redirected.</p>
        <a href="../builtins/stdtypes.html">If not, click here to continue.</a>
    </body>
</html>

though the JavaScript half will keep the anchor and query string.

[StanFromIreland]

There are conflicts now.

Also, a few additional sites that need updating:

InternalDocs/structure.md:* [`Doc/library/functions.rst`](../Doc/library/functions.rst)
InternalDocs/structure.md:* [`Doc/library/stdtypes.rst`](../Doc/library/stdtypes.rst)
Tools/unicode/makeunicodedata.py:#   * Doc/library/stdtypes.rst (four occurrences)

[nedbat]

I think this is done.

[StanFromIreland]

@nedbat can you please avoid force pushing, it makes it a little harder to review. See also the section in the Devguide.

[nedbat]

sorry, a habit from other repos.