add repo tag and commit associated with the build (#4571)

* add repo tag and commit associated with the build Signed-off-by: Niels Bantilan <[email protected]> * define html_context in import_projects extension Signed-off-by: Niels Bantilan <[email protected]> * always show repo tags Signed-off-by: Niels Bantilan <[email protected]> * update readthedocs config Signed-off-by: Niels Bantilan <[email protected]> * reapply change to .readthedocs.yaml Signed-off-by: Niels Bantilan <[email protected]> --------- Signed-off-by: Niels Bantilan <[email protected]>
flyteorg · Dec 13, 2023 · d5f0002 · d5f0002
1 parent 6c84e46
commit d5f0002
Show file tree

Hide file tree

Showing 3 changed files with 263 additions and 1 deletion.
diff --git a/docs/_ext/import_projects.py b/docs/_ext/import_projects.py
@@ -9,6 +9,7 @@
 from pathlib import Path
 from typing import Optional, List, Union
 
+import git
 from git import Repo
 from docutils import nodes
 from docutils.statemachine import StringList, string2lines
@@ -29,6 +30,7 @@ class ImportProjectsConfig:
 
 @dataclass
 class Project:
+    name: str
     source: str
     dest: str
     local: bool = False
@@ -99,6 +101,16 @@ def update_sys_path_for_flytekit(import_project_config: ImportProjectsConfig):
             sys.path.insert(0, dir_path)
 
 
+def update_html_context(project: Project, tag: str, commit: str, config: Config):
+    tag_url = f"{project.source}/releases/tag/{tag}"
+    commit_url = f"{project.source}/tree/{commit}"
+
+    config.html_context[f"{project.name}_tag"] = tag
+    config.html_context[f"{project.name}_tag_url"] = tag_url
+    config.html_context[f"{project.name}_commit"] = commit
+    config.html_context[f"{project.name}_commit_url"] = commit_url
+
+
 def import_projects(app: Sphinx, config: Config):
     """Clone projects from git or copy from local directory."""
     projects = [Project(**p) for p in config.import_projects]
@@ -112,17 +124,34 @@ def import_projects(app: Sphinx, config: Config):
     ):
         (srcdir / _dir).mkdir(parents=True, exist_ok=True)
 
+    if not hasattr(config, "html_context"):
+        config.html_context = {}
+
+    show_repo_tags = False
     for project in projects:
         if project.local:
             local_dir = srcdir / project.source
+            try:
+                repo = Repo(local_dir)
+                show_repo_tags = True
+            except git.InvalidGitRepositoryError:
+                repo = None
         else:
             local_dir = srcdir / import_projects_config.clone_dir / project.dest
             shutil.rmtree(local_dir, ignore_errors=True)
-            Repo.clone_from(project.source, local_dir)
+            repo = Repo.clone_from(project.source, local_dir)
+            show_repo_tags = True
 
         local_docs_path = local_dir / project.docs_path
         dest_docs_dir = srcdir / project.dest
 
+        # use the latest git tag when building docs
+        if repo:
+            tags = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)
+            tag = tags[-1]
+            update_html_context(project, str(tag), str(tag.commit)[:7], config)
+            repo.git.checkout(str(tag))
+
         if project.refresh or not dest_docs_dir.exists():
             shutil.rmtree(dest_docs_dir, ignore_errors=True)
             shutil.copytree(local_docs_path, dest_docs_dir, dirs_exist_ok=True)
@@ -134,6 +163,8 @@ def import_projects(app: Sphinx, config: Config):
             else:
                 subprocess.run(project.cmd)
 
+    config.html_context["show_repo_tags"] = show_repo_tags
+
     # remove cloned directories
     shutil.rmtree(import_projects_config.clone_dir)
 

diff --git a/docs/_templates/page.html b/docs/_templates/page.html
diff --git a/docs/conf.py b/docs/conf.py
@@ -350,6 +350,7 @@
 
 import_projects = [
     {
+        "name": "flytesnacks",
         "source": flytesnacks_local_path or "https://github.com/flyteorg/flytesnacks",
         "docs_path": "docs",
         "dest": "flytesnacks",
@@ -368,6 +369,7 @@
         "local": flytesnacks_local_path is not None,
     },
     {
+        "name": "flytekit",
         "source": flytekit_local_path or "https://github.com/flyteorg/flytekit",
         "docs_path": "docs/source",
         "dest": "api/flytekit",
@@ -380,12 +382,14 @@
         "local": flytekit_local_path is not None,
     },
     {
+        "name": "flytectl",
         "source": flytectl_local_path or "https://github.com/flyteorg/flytectl",
         "docs_path": "docs/source",
         "dest": "flytectl",
         "local": flytectl_local_path is not None,
     },
     {
+        "name": "flyteidl",
         "source": "../flyteidl",
         "docs_path": "protos",
         "dest": "protos",  # to stay compatible with flyteidl docs path naming