It Is Hard to Keep Track of the Instructions In the "Isolating Extension Modules" How-to

[ericsnowcurrently]

Documentation

(https://docs.python.org/3/howto/isolating-extensions.html)

This how-to doc contains a lot of useful information. However, it can be difficult to keep track of all the instructions it provides. It is also easy to miss important steps or lose track of everything that needs to be done. I expect that doing something about this would improve the experience of people porting modules to multi-phase init, reducing their frustration.

One thing that could help is a checklist (or two ¹) that condenses the instructions throughout the doc into a succinct TODO list. Imagine someone porting a module with the checklist open side-by-side with the code for the module they are porting. That would make it much easier to keep track of what needs to be (or has been) done.

The checklist would probably go in a later section of the doc, possibly at the very bottom. However, we would want a distinct link at the very top of the doc.

CC @encukou

Linked PRs

• gh-110812: Isolating Extension Modules HOWTO: List GC-related gotchas #111504
• [3.11] gh-110812: Isolating Extension Modules HOWTO: List GC-related gotchas (GH-111504) #112147
• [3.12] gh-110812: Isolating Extension Modules HOWTO: List GC-related gotchas (GH-111504) #112148

Footnotes

1. I expect we would have one checklist for converting a module to multi-phase init and one specifically for converting a static type to a heap type. ↩

[ericsnowcurrently]

@1st1, would something like the checklist I described have helped you much?