docs: Stop hard-coding Comet version in docs (#2326)

andygrove · web-flow · commit 4f123959e6eb · 2025-09-09T06:44:18.000-07:00
* Stop hard-coding Comet version in docs

* prep for review

* add warning for out-of-date docs

* add warning for out-of-date docs

* fix

* save

* fix
diff --git a/docs/generate-versions.py b/docs/generate-versions.py
@@ -23,8 +23,65 @@
 # of Comet
 
 import os
+from pathlib import Path
 
-for version in ["0.8", "0.9"]:
-    os.system(f"git clone --depth 1 https://github.com/apache/datafusion-comet.git -b branch-{version} comet-{version}")
-    os.system(f"mkdir temp/user-guide/{version}")
-    os.system(f"cp -rf comet-{version}/docs/source/user-guide/* temp/user-guide/{version}")
+def get_major_minor_version(version: str):
+    parts = version.split('.')
+    return f"{parts[0]}.{parts[1]}"
+
+def replace_in_files(root: str, filename_pattern: str, search: str, replace: str):
+    root_path = Path(root)
+    for file in root_path.rglob(filename_pattern):
+        text = file.read_text(encoding="utf-8")
+        updated = text.replace(search, replace)
+        if text != updated:
+            file.write_text(updated, encoding="utf-8")
+            print(f"Replaced {search} with {replace} in {file}")
+
+def insert_warning_after_asf_header(root: str, warning: str):
+    root_path = Path(root)
+    for file in root_path.rglob("*.md"):
+        lines = file.read_text(encoding="utf-8").splitlines(keepends=True)
+        new_lines = []
+        inserted = False
+        for line in lines:
+            new_lines.append(line)
+            if not inserted and "-->" in line:
+                new_lines.append(warning + "\n")
+                inserted = True
+        file.write_text("".join(new_lines), encoding="utf-8")
+
+def publish_released_version(version: str):
+    major_minor = get_major_minor_version(version)
+    os.system(f"git clone --depth 1 https://github.com/apache/datafusion-comet.git -b branch-{major_minor} comet-{major_minor}")
+    os.system(f"mkdir temp/user-guide/{major_minor}")
+    os.system(f"cp -rf comet-{major_minor}/docs/source/user-guide/* temp/user-guide/{major_minor}")
+    # Replace $COMET_VERSION with actual version
+    for file_pattern in ["*.md", "*.rst"]:
+        replace_in_files(f"temp/user-guide/{major_minor}", file_pattern, "$COMET_VERSION", version)
+
+def generate_docs(snapshot_version: str, latest_released_version: str, previous_versions: list[str]):
+
+    # Replace $COMET_VERSION with actual version for snapshot version
+    for file_pattern in ["*.md", "*.rst"]:
+        replace_in_files(f"temp/user-guide/latest", file_pattern, "$COMET_VERSION", snapshot_version)
+
+    # Add user guide content for latest released versions
+    publish_released_version(latest_released_version)
+
+    # Add user guide content for older released versions
+    for version in previous_versions:
+        publish_released_version(version)
+        # add warning that this is out-of-date documentation
+        warning = f"""```{{warning}}
+This is **out-of-date** documentation. The latest Comet release is version {latest_released_version}.
+```"""
+        major_minor = get_major_minor_version(version)
+        insert_warning_after_asf_header(f"temp/user-guide/{major_minor}", warning)
+
+if __name__ == "__main__":
+    print("Generating versioned user guide docs...")
+    snapshot_version = "0.10.0-SNAPSHOT"
+    latest_released_version = "0.9.1"
+    previous_versions = ["0.8.0"]
+    generate_docs(snapshot_version, latest_released_version, previous_versions)
diff --git a/docs/source/user-guide/0.8/index.rst b/docs/source/user-guide/0.8/index.rst
@@ -22,10 +22,10 @@
 Comet 0.8.x User Guide
 =======================
 
-.. _toc.user-guide-links-08:
+.. _toc.user-guide-links-$COMET_VERSION:
 .. toctree::
    :maxdepth: 1
-   :caption: Comet 0.8.x User Guide
+   :caption: Comet $COMET_VERSION User Guide
 
    Installing Comet <installation>
    Building From Source <source>
diff --git a/docs/source/user-guide/0.9/index.rst b/docs/source/user-guide/0.9/index.rst
@@ -22,10 +22,10 @@
 Comet 0.9.x User Guide
 =======================
 
-.. _toc.user-guide-links-09:
+.. _toc.user-guide-links-$COMET_VERSION:
 .. toctree::
    :maxdepth: 1
-   :caption: Comet 0.9.x User Guide
+   :caption: Comet $COMET_VERSION User Guide
 
    Installing Comet <installation>
    Building From Source <source>
diff --git a/docs/source/user-guide/latest/iceberg.md b/docs/source/user-guide/latest/iceberg.md
@@ -39,7 +39,7 @@ make release
 Set `COMET_JAR` env var:
 
 ```shell
-export COMET_JAR=`pwd`/spark/target/comet-spark-spark3.5_2.12-0.10.0-SNAPSHOT.jar
+export COMET_JAR=`pwd`/spark/target/comet-spark-spark3.5_2.12-$COMET_VERSION.jar
 ```
 
 ## Build Iceberg
diff --git a/docs/source/user-guide/latest/index.rst b/docs/source/user-guide/latest/index.rst
@@ -19,13 +19,13 @@
   :alt: DataFusion Comet Logo
 
 ================================
-Comet 0.10.0-SNAPSHOT User Guide
+Comet $COMET_VERSION User Guide
 ================================
 
-.. _toc.user-guide-links-latest:
+.. _toc.user-guide-links-$COMET_VERSION:
 .. toctree::
    :maxdepth: 1
-   :caption: Comet 0.10.0-SNAPSHOT User Guide
+   :caption: Comet $COMET_VERSION User Guide
 
    Installing Comet <installation>
    Building From Source <source>
diff --git a/docs/source/user-guide/latest/installation.md b/docs/source/user-guide/latest/installation.md
@@ -30,9 +30,7 @@ Make sure the following requirements are met and software installed on your mach
 
 ### Supported Spark Versions
 
-Comet currently supports the following versions of Apache Spark. Note that this documentation is for the main
-branch. Please refer to the version of this documentation in the appropriate GitHub release branch for released
-Comet versions.
+Comet $COMET_VERSION supports the following versions of Apache Spark.
 
 We recommend only using Comet with Spark versions where we currently have both Comet and Spark tests enabled in CI.
 Other versions may work well enough for development and evaluation purposes.
@@ -84,7 +82,7 @@ See the [Comet Kubernetes Guide](kubernetes.md) guide.
 Make sure `SPARK_HOME` points to the same Spark version as Comet was built for.
 
 ```shell
-export COMET_JAR=spark/target/comet-spark-spark3.5_2.12-0.10.0-SNAPSHOT.jar
+export COMET_JAR=spark/target/comet-spark-spark3.5_2.12-$COMET_VERSION.jar
 
 $SPARK_HOME/bin/spark-shell \
     --jars $COMET_JAR \
@@ -140,7 +138,7 @@ explicitly contain Comet otherwise Spark may use a different class-loader for th
 components which will then fail at runtime. For example:
 
 ```
---driver-class-path spark/target/comet-spark-spark3.5_2.12-0.10.0-SNAPSHOT.jar
+--driver-class-path spark/target/comet-spark-spark3.5_2.12-$COMET_VERSION.jar
 ```
 
 Some cluster managers may require additional configuration, see <https://spark.apache.org/docs/latest/cluster-overview.html>
