Repository navigation
Doc/c-api/init.rst is way too big #141811
Description
Documentation
While working on #141810, I noticed that init.rst covers three very complicated topics:
- Interpreter initialization and finalization
- Threads and concurrency
- Subinterpreters
This makes it pretty huge and difficult to find things. I think we should split this up into two pages. Let's have a page for interpreter-related topics (initialization, finalization, subinterpreters), and a separate page for anything related to threads (PyMutex, critical sections, thread states, etc.).
Linked PRs
Metadata
Metadata
Assignees
Projects
- Status
Activity
StanFromIreland commentedon Nov 21, 2025
These moves are quite unfortunate for translations, but I’ll try to keep track of this and inform translation teams. Are you going to be backporting to 3.14?
ZeroIntensity commentedon Nov 21, 2025
That would be ideal. Otherwise, any changes to the docs of those APIs will have conflicts when backporting. Is there anything that can be done to improve this for translations?
vstinner commentedon Nov 21, 2025
It could be 3 pages:
StanFromIreland commentedon Nov 21, 2025
Automatically, for non-Transifex translations (TX memory should merge them back in), no. It will require each translation team to manually merge the messages back in from an older commit. Due to this, I want to notify them ASAP after merge to recover the message and not re-translate things. I'll look into adding a guide for it to the devguide.
ZeroIntensity commentedon Nov 21, 2025
Sounds good. I'll work on this once #141810 is done.
picnixz commentedon Nov 22, 2025
FTR, breaking the file might also break SEO and (possibly) intersphinx if we change the label names. See also #126053. One reason we still didn't break down some very large pages:
ZeroIntensity commentedon Nov 22, 2025
I think that isn't as important here; C API docs are going to be significantly less linked than something like
datamodel.rst. But, according to that issue, we can redirect things anyway.picnixz commentedon Nov 22, 2025
Yeah but I would rather have the EB make a decision here instead of use core devs: see https://discuss.python.org/t/restructuring-the-stdlib-docs/102506.
ZeroIntensity commentedon Nov 22, 2025
How do I ask the EB?
StanFromIreland commentedon Nov 22, 2025
Open an issue in their repo, python/editoral-board.
hugovk commentedon Feb 3, 2026
We discussed this in the Docs WG meeting and are generally in favour: python/editorial-board#37 (comment).
gh-141811: Split up `init.rst` into multiple pages (GH-144844)
[3.14] pythongh-141811: Split up `init.rst` into multiple pages (pyth…
[3.14] gh-141811: Split up `init.rst` into multiple pages (GH-144844) (…
pythongh-141811: Split up `init.rst` into multiple pages (pythonGH-14…
pythongh-141811: Split up `init.rst` into multiple pages (pythonGH-14…