gh-134160: Improve note on multi-phase init & subinterpreters

Author: encukou

Doc/c-api/module.rst

@@ -302,8 +302,13 @@ using :c:func:`PyModule_GetState`), or its contents (such as the module's
 :attr:`~object.__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
 
 All modules created using multi-phase initialization are expected to support
-:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
-are independent is typically enough to achieve this.
+:ref:`sub-interpreters <sub-interpreter-support>`.
+Typically, extensions ensure this in one of these ways:
+
+- :ref:`isolating module instances <isolating-extensions-howto>`,
+- :ref:`raising an error on repeated initialization <isolating-extensions-optout>`, or
+- limiting a module to the main interpreter using
+  :c:data:`Py_mod_multiple_interpreters`.
 
 To request multi-phase initialization, the initialization function
 (PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty

Doc/howto/isolating-extensions.rst

@@ -168,7 +168,7 @@ possible, consider explicit locking.
 If it is necessary to use process-global state, the simplest way to
 avoid issues with multiple interpreters is to explicitly prevent a
 module from being loaded more than once per process—see
-`Opt-Out: Limiting to One Module Object per Process`_.
+:ref:`isolating-extensions-optout`.
 
 
 Managing Per-Module State
@@ -207,6 +207,8 @@ An example of a module with per-module state is currently available as
 example module initialization shown at the bottom of the file.
 
 
+.. _isolating-extensions-optout:
+
 Opt-Out: Limiting to One Module Object per Process
 --------------------------------------------------