This is an automated email from the ASF dual-hosted git repository.
ephraimanierobi pushed a commit to branch v2-7-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 2f4f449b941e1d5908934cd60a45dd6726fdaa42
Author: Andrey Anshin <andrey.ans...@taragol.is>
AuthorDate: Sun Oct 8 22:51:05 2023 +0400
Fix variables substitution in Airflow Documentation (#34462)
(cherry picked from commit 530ebb58b6b85444b62618684b5741b9d6dd715e)
---
docs/conf.py | 33 +++++++++++++++++------------
docs/docker-stack/build.rst | 2 +-
docs/exts/extra_files_with_substitutions.py | 21 ++++++++++++------
3 files changed, 35 insertions(+), 21 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index d26edb6c82..cfd8ab01e3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -102,6 +102,12 @@ os.environ["AIRFLOW_PACKAGE_NAME"] = PACKAGE_NAME
# 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 @@ version = PACKAGE_VERSION
# 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 @@ if PACKAGE_NAME == "apache-airflow-providers":
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,9 +329,8 @@ if PACKAGE_NAME == "apache-airflow":
]
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",
@@ -333,7 +338,7 @@ if PACKAGE_NAME == "apache-airflow":
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
-------------------------------------------------------
diff --git a/docs/docker-stack/build.rst b/docs/docker-stack/build.rst
index 41a52b0c07..6ede683014 100644
--- a/docs/docker-stack/build.rst
+++ b/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
diff --git a/docs/exts/extra_files_with_substitutions.py
b/docs/exts/extra_files_with_substitutions.py
index cb91b163f0..e0e0f20f05 100644
--- a/docs/exts/extra_files_with_substitutions.py
+++ b/docs/exts/extra_files_with_substitutions.py
@@ -19,19 +19,27 @@ from __future__ import annotations
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,
