Fix variables substitution in Airflow Documentation (#34462)

(cherry picked from commit 530ebb5)

docs/conf.py

@@ -102,6 +102,12 @@
 # behavior of the utils.apply_default that was hiding function headers
 os.environ["BUILDING_AIRFLOW_DOCS"] = "TRUE"
 
+# Use for generate rst_epilog and other post-generation substitutions
+global_substitutions = {
+    "version": PACKAGE_VERSION,
+    "airflow-version": airflow.__version__,
+}
+
 # == Sphinx configuration ======================================================
 
 # -- Project information -------------------------------------------------------
@@ -114,18 +120,19 @@
 # The full version, including alpha/beta/rc tags.
 release = PACKAGE_VERSION
 
-rst_epilog = f"""
-.. |version| replace:: {version}
-.. |airflow-version| replace:: {airflow.__version__}
-.. |experimental| replace:: This is an :ref:`experimental feature <experimental>`.
-"""
-
-smartquotes_excludes = {"builders": ["man", "text", "spelling"]}
-
-
 # -- General configuration -----------------------------------------------------
 # See: https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+rst_epilog = "\n".join(
+    f".. |{key}| replace:: {replace}"
+    for key, replace in {
+        **global_substitutions,
+        "experimental": "This is an :ref:`experimental feature <experimental>`.",
+    }.items()
+)
+
+smartquotes_excludes = {"builders": ["man", "text", "spelling"]}
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -171,8 +178,7 @@
 elif PACKAGE_NAME == "helm-chart":
     extensions.append("sphinx_jinja")
 elif PACKAGE_NAME == "docker-stack":
-    # No extra extensions
-    pass
+    extensions.append("extra_files_with_substitutions")
 elif PACKAGE_NAME.startswith("apache-airflow-providers-"):
     extensions.extend(
         [
@@ -323,17 +329,16 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
     ]
     html_extra_with_substitutions = [
         f"{ROOT_DIR}/docs/apache-airflow/howto/docker-compose/docker-compose.yaml",
-        f"{ROOT_DIR}/docs/docker-stack/build.rst",
     ]
-    # Replace "|version|" in links
+    # Substitute in links
     manual_substitutions_in_generated_html = [
         "installation/installing-from-pypi.html",
         "installation/installing-from-sources.html",
     ]
 if PACKAGE_NAME.startswith("apache-airflow-providers"):
     manual_substitutions_in_generated_html = ["example-dags.html", "operators.html", "index.html"]
 if PACKAGE_NAME == "docker-stack":
-    # Replace "|version|" inside ```` quotes
+    # Substitute in links
     manual_substitutions_in_generated_html = ["build.html"]
 
 # -- Theme configuration -------------------------------------------------------

docs/docker-stack/build.rst

@@ -533,7 +533,7 @@ Before attempting to customize the image, you need to download flexible and cust
 You can extract the officially released version of the Dockerfile from the
 `released sources <https://airflow.apache.org/docs/apache-airflow/stable/installation/installing-from-sources.html>`_.
 You can also conveniently download the latest released version
-`from GitHub <https://raw.githubusercontent.com/apache/airflow/|version|/Dockerfile>`_. You can save it
+`from GitHub <https://raw.githubusercontent.com/apache/airflow/|airflow-version|/Dockerfile>`_. You can save it
 in any directory - there is no need for any other files to be present there. If you wish to use your own
 files (for example custom configuration of ``pip`` or your own ``requirements`` or custom dependencies,
 you need to use ``DOCKER_CONTEXT_FILES`` build arg and place the files in the directory pointed at by

docs/exts/extra_files_with_substitutions.py

@@ -19,19 +19,27 @@
 import os
 
 
-def copy_docker_compose(app, exception):
+def _manual_substitution(line: str, replacements: dict[str, str]) -> str:
+    for value, repl in replacements.items():
+        line = line.replace(f"|{value}|", repl)
+    return line
+
+
+def build_postprocess(app, exception):
     """Sphinx "build-finished" event handler."""
     from sphinx.builders import html as builders
 
     if exception or not isinstance(app.builder, builders.StandaloneHTMLBuilder):
         return
 
+    global_substitutions = app.config.global_substitutions
+
     # Replace `|version|` in the docker-compose.yaml that requires manual substitutions
     for path in app.config.html_extra_with_substitutions:
         with open(path) as file:
             with open(os.path.join(app.outdir, os.path.basename(path)), "w") as output_file:
                 for line in file:
-                    output_file.write(line.replace("|version|", app.config.version))
+                    output_file.write(_manual_substitution(line, global_substitutions))
 
     # Replace `|version|` in the installation files that requires manual substitutions (in links)
     for path in app.config.manual_substitutions_in_generated_html:
@@ -41,15 +49,16 @@ def copy_docker_compose(app, exception):
             os.path.join(app.outdir, os.path.dirname(path), os.path.basename(path)), "w"
         ) as output_file:
             for line in content:
-                output_file.write(line.replace("|version|", app.config.version))
+                output_file.write(_manual_substitution(line, global_substitutions))
 
 
 def setup(app):
     """Setup plugin"""
-    app.connect("build-finished", copy_docker_compose)
+    app.connect("build-finished", build_postprocess)
 
-    app.add_config_value("html_extra_with_substitutions", [], "[str]")
-    app.add_config_value("manual_substitutions_in_generated_html", [], "[str]")
+    app.add_config_value("html_extra_with_substitutions", [], "html", [str])
+    app.add_config_value("manual_substitutions_in_generated_html", [], "html", [str])
+    app.add_config_value("global_substitutions", {}, "html", [dict])
 
     return {
         "parallel_write_safe": True,