Explain how to add an extension module (python#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.
iritkatriel · Sep 11, 2024 · 3070b7c · 3070b7c
1 parent 89254a9
commit 3070b7c
Show file tree

Hide file tree

Showing 3 changed files with 703 additions and 5 deletions.
diff --git a/_extensions/ubuntu_version.py b/_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}
diff --git a/conf.py b/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"