Explain how to add an extension module (#1350)

* explain how to add modules

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Update extension-modules.rst

* Address Hugo's feedback

* Update extension-modules.rst

* Update extension-modules.rst

* improvements

- use distinct names for files to highlight differences in configurations
- be more precise on the terminology of an extension module
- explain how to build a required module (always built-in) vs an optional module (built-in or dynamic)
- address Ezio's review

* fixup! sphinx

* fixup! indents

* fixup! warnings

* improve sections

* fix markup

* improve titles

* improve presentation

* fixup! markup

* simplify snippets

* improvements

* improvements

* some rewordings and cleanups

* simplify wording

* address Erlend's review

* fix indents?

* add ref to clinic everywhere when needed

* fix typos

* address encukou's review

* improve the page flow

* use sentence case

(that's the reason why the previous title felt wrong to me!)

* add podman tip

* address rest of the review

* address Alyssa's review

* add details

* address review

- Add details on `Py_BUILD_CORE_*` macros
- Add tips for `Py_LIMITED_API`

* Make it easier to update the required ubuntu version

* fixup!

* fixup!

* improve comment

* use double quotes instead of single quotes

* Address Carol's review.

Author: picnixz

_extensions/ubuntu_version.py

@@ -0,0 +1,28 @@
+"""Sphinx extension to update the required Ubuntu version.
+
+The required Ubuntu version should be specified in conf.py by::
+
+    configure_ubuntu_version = "MAJOR.MINOR"  # e.g., "22.04"
+
+The version must match the one used to regenerate the configure script in
+https://github.com/python/cpython/blob/main/Tools/build/regen-configure.sh.
+"""
+
+from sphinx.errors import ExtensionError
+
+
+def replace_ubuntu_version(app, docname, source):
+    """Replace all occurrences of $CONFIGURE_UBUNTU_VERSION$.
+
+    This is needed since RST replacement via ``|...|`` is not supported
+    in code-blocks directives.
+    """
+    if (ubuntu_version := app.config.configure_ubuntu_version) is None:
+        raise ExtensionError("configure_ubuntu_version is not set in conf.py")
+    source[0] = source[0].replace("$CONFIGURE_UBUNTU_VERSION$", ubuntu_version)
+
+
+def setup(app):
+    app.add_config_value("configure_ubuntu_version", None, "env", types=(str,))
+    app.connect("source-read", replace_ubuntu_version)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

conf.py

@@ -1,6 +1,10 @@
+import sys
 import time
 
+sys.path.insert(0, '_extensions')
+
 extensions = [
+    'ubuntu_version',
     'notfound.extension',
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
@@ -194,3 +198,7 @@
 copybutton_prompt_text = "$ "
 # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#honor-line-continuation-characters-when-copying-multline-snippets
 copybutton_line_continuation_character = "\\"
+
+# Must be synchronized with the Ubuntu image version in
+# https://github.com/python/cpython/blob/main/Tools/build/regen-configure.sh
+configure_ubuntu_version = "22.04"