add repo tag and commit associated with the build

docs/.readthedocs.yaml

@@ -15,7 +15,7 @@ build:
     - conda info
     - conda env list
     - cat docs/conf.py
-    - cd docs && /home/docs/monodocs-env/bin/python -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html
+    - cd docs && SHOW_REPO_TAGS=1 /home/docs/monodocs-env/bin/python -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

docs/_ext/import_projects.py

@@ -8,6 +8,7 @@
 from pathlib import Path
 from typing import Optional, List, Union
 
+import git
 from git import Repo
 from sphinx.application import Sphinx
 from sphinx.config import Config
@@ -24,6 +25,7 @@ class ImportProjectsConfig:
 
 @dataclass
 class Project:
+    name: str
     source: str
     dest: str
     local: bool = False
@@ -54,6 +56,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]
@@ -67,17 +79,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)
@@ -89,6 +118,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)
 

docs/conf.py

@@ -344,6 +344,7 @@
 
 import_projects = [
     {
+        "name": "flytesnacks",
         "source": flytesnacks_local_path or "https://github.com/flyteorg/flytesnacks",
         "docs_path": "docs",
         "dest": "flytesnacks",
@@ -362,6 +363,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",
@@ -374,12 +376,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