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,