Docs: split builtins to their own page from library - #156682
Conversation
37b2ad3 to
10c84e6
Compare
|
Also: is this NEWS-worthy? |
I don't see a need for one here, I think the docs speak for themselves. |
Documentation build overview
74 files changed ·
|
hugovk
left a comment
hugovk
left a comment
There was a problem hiding this comment.
Shall we name the new Doc/library/builtin-index.rst as Doc/builtins/index.rst instead?
Then instead of:
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
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
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.
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. |
We use |
I knew rediraffe was somewhere! 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. |
c6de373 to
ea9966e
Compare
|
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? |
Yes, see the line with an asyncio file for the required format. |
hugovk
added
needs backport to 3.14
| semantics of the Python language, and :ref:`builtins-index` describes | ||
| the built-ins, this library reference manual |
There was a problem hiding this comment.
With this addition of built-ins, it makes sense to rewrite this paragraph. I think it would be preferable to order the paragraph more directly:
- State that "This library reference manual describes the standard library that is ...distributions."
- Simplify the "While..." clause to state directly that the reference index and builtins index.
| language. It is terse, but attempts to be exact and complete. The semantics of | ||
| non-essential built-in object types and of the built-in functions and modules | ||
| are described in :ref:`library-index`. For an informal introduction to the | ||
| built-in object types and of the built-in functions and modules |
There was a problem hiding this comment.
Maybe "standard library modules"
There was a problem hiding this comment.
I've rewritten and split these paragraphs, though tbh, we're repeating ourselves by having each section also mention what the other sections are.
|
Merge in 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 |
|
Sorry, @nedbat, I could not cleanly backport this to |
|
Sorry, @nedbat, I could not cleanly backport this to |
|
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. |
bedevere-app
Bot
removed
the
needs backport to 3.15
#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)
|
I've added server-side redirects in python/psf-salt#651. |
6 participants
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.