docs: support conditional content for snapshot vs release builds

docs/generate-versions.py

@@ -52,6 +52,51 @@ def replace_in_files(root: str, filename_pattern: str, search: str, replace: str
             file.write_text(updated, encoding="utf-8")
             print(f"Replaced {search} with {replace} in {file}")
 
+
+def strip_conditional_blocks(root: str, mode: str):
+    if mode == "snapshot":
+        keep_marker = "<!-- IF_SNAPSHOT -->"
+        drop_marker = "<!-- IF_RELEASE -->"
+    elif mode == "release":
+        keep_marker = "<!-- IF_RELEASE -->"
+        drop_marker = "<!-- IF_SNAPSHOT -->"
+    else:
+        raise ValueError(f"mode must be 'snapshot' or 'release', got {mode!r}")
+    end_marker = "<!-- ENDIF -->"
+
+    root_path = Path(root)
+    for file_pattern in ("*.md", "*.rst"):
+        for file in root_path.rglob(file_pattern):
+            lines = file.read_text(encoding="utf-8").splitlines(keepends=True)
+            out = []
+            state = None  # None, "keep", or "drop"
+            changed = False
+            for lineno, line in enumerate(lines, start=1):
+                stripped = line.strip()
+                if stripped == keep_marker or stripped == drop_marker:
+                    if state is not None:
+                        raise ValueError(
+                            f"{file}:{lineno}: conditional block opened while already inside a block"
+                        )
+                    state = "keep" if stripped == keep_marker else "drop"
+                    changed = True
+                elif stripped == end_marker:
+                    if state is None:
+                        raise ValueError(
+                            f"{file}:{lineno}: ENDIF with no matching opener"
+                        )
+                    state = None
+                    changed = True
+                elif state == "drop":
+                    changed = True
+                else:
+                    out.append(line)
+            if state is not None:
+                raise ValueError(f"{file}: unclosed conditional block")
+            if changed:
+                file.write_text("".join(out), encoding="utf-8")
+                print(f"Processed conditional blocks ({mode}) in {file}")
+
 def insert_warning_after_asf_header(root: str, warning: str):
     root_path = Path(root)
     for file in root_path.rglob("*.md"):
@@ -78,12 +123,17 @@ def publish_released_version(version: str):
     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}/{dir}/* temp/user-guide/{major_minor}")
+    # Strip snapshot-only content; keep release-only content
+    strip_conditional_blocks(f"temp/user-guide/{major_minor}", "release")
     # 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]):
 
+    # Strip release-only content; keep snapshot-only content for the latest (snapshot) docs
+    strip_conditional_blocks("temp/user-guide/latest", "snapshot")
+
     # 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)

docs/source/user-guide/latest/installation.md

@@ -57,6 +57,15 @@ Cloud Service Providers.
 
 ## Using a Published JAR File
 
+<!-- IF_SNAPSHOT -->
+
+This documentation is for the current development version of Comet. Published jar files are only available for released versions.
+To use this version of Comet, see [Building from source](source.md).
+
+<!-- ENDIF -->
+
+<!-- IF_RELEASE -->
+
 Comet jar files are available in [Maven Central](https://central.sonatype.com/namespace/org.apache.datafusion) for amd64 and arm64 architectures for Linux. For Apple macOS, it
 is currently necessary to build from source.
 
@@ -66,15 +75,14 @@ arm64 build uses the `neoverse-n1` target, which is a common baseline for ARM co
 Azure after 2019. If the Comet library fails for SIGILL (illegal instruction), please open an issue on the GitHub
 repository describing your environment, and [build from source] for your target architecture.
 
-Here are the direct links for downloading the Comet $COMET_VERSION jar file. Note that these links are not valid if
-you are viewing the documentation for the latest `SNAPSHOT` release, or for the latest release while it is still going
-through the release vote. Release candidate jars can be found [here](https://repository.apache.org/#nexus-search;quick~org.apache.datafusion).
+Here are the direct links for downloading the Comet $COMET_VERSION jar file.
 
 - [Comet plugin for Spark 3.4 / Scala 2.12](https://repo1.maven.org/maven2/org/apache/datafusion/comet-spark-spark3.4_2.12/$COMET_VERSION/comet-spark-spark3.4_2.12-$COMET_VERSION.jar)
 - [Comet plugin for Spark 3.4 / Scala 2.13](https://repo1.maven.org/maven2/org/apache/datafusion/comet-spark-spark3.4_2.13/$COMET_VERSION/comet-spark-spark3.4_2.13-$COMET_VERSION.jar)
 - [Comet plugin for Spark 3.5 / Scala 2.12](https://repo1.maven.org/maven2/org/apache/datafusion/comet-spark-spark3.5_2.12/$COMET_VERSION/comet-spark-spark3.5_2.12-$COMET_VERSION.jar)
 - [Comet plugin for Spark 3.5 / Scala 2.13](https://repo1.maven.org/maven2/org/apache/datafusion/comet-spark-spark3.5_2.13/$COMET_VERSION/comet-spark-spark3.5_2.13-$COMET_VERSION.jar)
 - [Comet plugin for Spark 4.0 / Scala 2.13 (Experimental)](https://repo1.maven.org/maven2/org/apache/datafusion/comet-spark-spark4.0_2.13/$COMET_VERSION/comet-spark-spark4.0_2.13-$COMET_VERSION.jar)
+<!-- ENDIF -->
 
 ## Building from source