Repository navigation
For readers -- split up init.rst #37
Description
- Link to discussion about the proposal (Discourse or GitHub):
Doc/c-api/init.rstis way too big
I would like to split up the init.rst file in the C API documentation into three separate pages:
- Interpreter lifecycle (initialization and finalization).
- Concurrency (the GIL, thread states, synchronization).
- Subinterpreters (
Py_NewInterpreter*,PyInterpreterConfig) +PyInterpreterState*APIs.
We might even want an additional page for profiling (PyRefTracer and PyTrace*).
I've heard pushback because this would break external references to the existing items on that page.
Activity
nedbat commentedon Feb 3, 2026
Does this need a decision from the EB? Lots of pages get refactored over time, this one could as well.
ZeroIntensity commentedon Feb 3, 2026
I was told that we needed an EB decision here.
nedbat commentedon Feb 3, 2026
Sorry, I see the longer issue now. "Splitting up init.rst" got mixed together with "Splitting pages in general" which pulls in "Splitting up the data model page", which is a huge can of worms and a huge effort.
Splitting up init.rst seems straightforward to me. There is a logistical tooling question about the redirects. We discussed this at the Docs WG meeting today. Petr is going to look into the best options for handling incoming URLs that need redirecting.
hugovk commentedon Feb 3, 2026
[Repeating some of Ned's comments]
We discussed this in the monthly Docs WG meeting and we were generally in favour of the refactor.
If there's good pedagogical reasons to do split it, let's do it, and we'll figure out solutions to any technical issues.
We have other huge pages like
datamodel.rstthat would benefit from being split up, and thisinit.rstwould be a good one to do first, as it's not so big and not visited as much asdatamodel.rst.SEO may get worse in the short term, but in the long term, I believe smaller, more focused pages will have much better SEO.
Intersphinx should be fine, Sphinx will link to the new place.
Non-intersphinx anchors are harder, so we'll have to think about those. We might need something like this or have some JavaScript tooling to deal with it, or possibly Nginx config (but I think an internal-to-docs solution would be nicer).
nedbat commentedon Feb 11, 2026
We also tasked @encukou to look into tooling for redirects.
ZeroIntensity commentedon Feb 15, 2026
Thanks everyone, I'll close this now that I have a PR up: python/cpython#144844.
While we figure out the redirects, my current solution is to have an orphan
init.rstfile that links to the new pages.