For readers -- split up `init.rst`

[ZeroIntensity]

• Link to discussion about the proposal (Discourse or GitHub): Doc/c-api/init.rst is way too big

I would like to split up the init.rst file in the C API documentation into three separate pages:

1. Interpreter lifecycle (initialization and finalization).
2. Concurrency (the GIL, thread states, synchronization).
3. 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.

[nedbat]

Does this need a decision from the EB? Lots of pages get refactored over time, this one could as well.

[ZeroIntensity]

I was told that we needed an EB decision here.

[nedbat]

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]

[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.rst that would benefit from being split up, and this init.rst would be a good one to do first, as it's not so big and not visited as much as datamodel.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]

We also tasked @encukou to look into tooling for redirects.

[ZeroIntensity]

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.rst file that links to the new pages.