From 506093ead9a5b51af0bc62e480e45747d150164f Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 3 Dec 2024 21:30:41 +0000 Subject: [PATCH 1/6] add versions config file --- docs/docsite/versions.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/docsite/versions.yaml diff --git a/docs/docsite/versions.yaml b/docs/docsite/versions.yaml new file mode 100644 index 00000000000..29f9fe4681e --- /dev/null +++ b/docs/docsite/versions.yaml @@ -0,0 +1,20 @@ +package: + active: + - devel + - stable-2.18 + - stable-2.17 + - stable-2.16 + eol: + - stable-2.15 + - stable-2.14 + - stable-2.13 +core: + active: + - devel + - stable-2.18 + - stable-2.17 + - stable-2.16 + eol: + - stable-2.15 + - stable-2.14 + - stable-2.13 From ede97c73476c696bc7c14bcb76742295e6feb5be Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 3 Dec 2024 21:31:10 +0000 Subject: [PATCH 2/6] add eol banner sphinx extension --- docs/docsite/rst/_ext/__init__.py | 5 +++ docs/docsite/rst/_ext/eol_version.py | 56 ++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/docsite/rst/_ext/__init__.py create mode 100644 docs/docsite/rst/_ext/eol_version.py diff --git a/docs/docsite/rst/_ext/__init__.py b/docs/docsite/rst/_ext/__init__.py new file mode 100644 index 00000000000..bb3b751bbe9 --- /dev/null +++ b/docs/docsite/rst/_ext/__init__.py @@ -0,0 +1,5 @@ +from .eol_version import setup + +__version__ = '1.0.0' + +__all__ = ['setup'] diff --git a/docs/docsite/rst/_ext/eol_version.py b/docs/docsite/rst/_ext/eol_version.py new file mode 100644 index 00000000000..dd5c020bf15 --- /dev/null +++ b/docs/docsite/rst/_ext/eol_version.py @@ -0,0 +1,56 @@ +import subprocess +from pathlib import Path + +import yaml +from docutils import nodes +from jinja2 import Template +from sphinx.transforms import Transform + + +class EOLVersionCheck(Transform): + # pylint: disable=too-few-public-methods + default_priority = 999 + + def apply(self): + env = self.document.settings.env + app = env.app + + if app.tags.has("core"): + build_type = "core" + elif app.tags.has("ansible"): + build_type = "package" + else: + return + + try: + branch = subprocess.check_output( + ["git", "rev-parse", "--abbrev-ref", "HEAD"], text=True + ).strip() + except subprocess.CalledProcessError as e: + print(f"Git error: {e}") + return + + yaml_path = Path(env.srcdir).parent / "versions.yaml" + template_path = Path(env.srcdir).parent / ".templates" / "eol_banner.html" + + with open(yaml_path, "r", encoding="utf-8") as f: + versions = yaml.safe_load(f) + + with open(template_path, "r", encoding="utf-8") as f: + template = Template(f.read()) + + if branch in versions[build_type]["eol"]: + banner_html = template.render( + version=branch, active_versions=versions[build_type]["active"] + ) + banner = nodes.raw("", banner_html, format="html") + self.document.insert(0, banner) + + +def setup(app): + app.add_transform(EOLVersionCheck) + return { + "version": "1.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } From e7b74f5454526d800c2cb58855c0551507784a94 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 3 Dec 2024 21:31:36 +0000 Subject: [PATCH 3/6] update sphinx conf to use extension --- docs/docsite/rst/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 011ab32baea..f3465fcef5e 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -25,6 +25,7 @@ # sys.path.append(os.path.abspath('some/directory')) # sys.path.insert(0, os.path.join('ansible', 'lib')) +sys.path.insert(0, os.path.abspath('.')) # We want sphinx to document the ansible modules contained in this repository, # not those that may happen to be installed in the version @@ -65,6 +66,7 @@ 'notfound.extension', 'sphinx_antsibull_ext', # provides CSS for the plugin/module docs generated by antsibull 'sphinx_copybutton', + '_ext.eol_version', ] # Later on, add 'sphinx.ext.viewcode' to the list if you want to have @@ -227,7 +229,6 @@ html_context = { 'display_github': 'True', 'show_sphinx': False, - 'is_eol': False, 'github_user': 'ansible', 'github_repo': 'ansible-documentation', 'github_version': 'devel', From d9961cb44672eb9a6e9ce78b3c5445585a2d8841 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 3 Dec 2024 21:31:53 +0000 Subject: [PATCH 4/6] move eol banner to separate file and format --- docs/docsite/.templates/banner.html | 15 +++------------ docs/docsite/.templates/eol_banner.html | 6 ++++++ 2 files changed, 9 insertions(+), 12 deletions(-) create mode 100644 docs/docsite/.templates/eol_banner.html diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html index d4ece6636da..f20bdd8ee2d 100644 --- a/docs/docsite/.templates/banner.html +++ b/docs/docsite/.templates/banner.html @@ -1,10 +1,4 @@ -{% if is_eol %} -{# Creates a banner at the top of the page for EOL versions. #} - -{% else %} - -{% endif %} + diff --git a/docs/docsite/.templates/eol_banner.html b/docs/docsite/.templates/eol_banner.html new file mode 100644 index 00000000000..f28df49da7b --- /dev/null +++ b/docs/docsite/.templates/eol_banner.html @@ -0,0 +1,6 @@ +{# Creates a banner at the top of the page for EOL versions. #} + From e30debf4063ebcbde2978619d97075f87f9e8402 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 4 Dec 2024 11:13:56 +0000 Subject: [PATCH 5/6] rm banner variables for simplicity --- docs/docsite/rst/_ext/eol_version.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/docsite/rst/_ext/eol_version.py b/docs/docsite/rst/_ext/eol_version.py index dd5c020bf15..b30f14bfb48 100644 --- a/docs/docsite/rst/_ext/eol_version.py +++ b/docs/docsite/rst/_ext/eol_version.py @@ -40,9 +40,7 @@ def apply(self): template = Template(f.read()) if branch in versions[build_type]["eol"]: - banner_html = template.render( - version=branch, active_versions=versions[build_type]["active"] - ) + banner_html = template.render() banner = nodes.raw("", banner_html, format="html") self.document.insert(0, banner) From 59ec15b5e4c5209b8e5cece837f0fc5074fecc4d Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 4 Dec 2024 11:22:18 +0000 Subject: [PATCH 6/6] add some type hints --- docs/docsite/rst/_ext/eol_version.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/_ext/eol_version.py b/docs/docsite/rst/_ext/eol_version.py index b30f14bfb48..673d2eae0ed 100644 --- a/docs/docsite/rst/_ext/eol_version.py +++ b/docs/docsite/rst/_ext/eol_version.py @@ -1,5 +1,6 @@ import subprocess from pathlib import Path +from typing import Any, Dict import yaml from docutils import nodes @@ -11,7 +12,7 @@ class EOLVersionCheck(Transform): # pylint: disable=too-few-public-methods default_priority = 999 - def apply(self): + def apply(self) -> None: env = self.document.settings.env app = env.app @@ -45,7 +46,7 @@ def apply(self): self.document.insert(0, banner) -def setup(app): +def setup(app) -> Dict[str, Any]: app.add_transform(EOLVersionCheck) return { "version": "1.0",