Autogenerate the doc antora.yml

patch by Mick Semb Wever; reviewed by Anthony Grasso for CASSANDRA-17375

.gitignore

@@ -10,6 +10,7 @@ logs/
 data/
 !test/data
 conf/hotspot_compiler
+doc/antora.yml
 doc/cql3/CQL.html
 doc/build/
 lib/

doc/Makefile

@@ -11,6 +11,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+GENERATE_ANTORA_YML = ./scripts/gen-antora-yml.py
 GENERATE_NODETOOL_DOCS = ./scripts/gen-nodetool-docs.py
 MAKE_CASSANDRA_YAML = ./scripts/convert_yaml_to_adoc.py ../conf/cassandra.yaml ./modules/cassandra/pages/managing/configuration/cass_yaml_file.adoc
 PROCESS_NATIVE_PROC_SPECS = ./scripts/process-native-protocol-specs-in-docker.sh
@@ -21,6 +22,7 @@ html:
 
 .PHONY: gen-asciidoc
 gen-asciidoc:
+	python3 $(GENERATE_ANTORA_YML)
 	@mkdir -p modules/cassandra/pages/managing/tools/nodetool
 	@mkdir -p modules/cassandra/examples/TEXT/NODETOOL
 	python3 $(GENERATE_NODETOOL_DOCS)

doc/README.md

@@ -36,7 +36,9 @@ The source for the official documentation for Apache Cassandra can be found in
 the `modules/cassandra/pages` subdirectory. The documentation uses [antora](http://www.antora.org/)
 and is thus written in [asciidoc](http://asciidoc.org).
 
-To generate the asciidoc files for cassandra.yaml and the nodetool commands, run (from project root):
+The `antora.yml` file is auto-generated and should not be manually edited. It is generated from the version in `build.xml` using `scripts/gen-antora-yml.py` and automatically detects whether building from a release tag or branch HEAD to set the appropriate version.
+
+To generate the asciidoc files (including antora.yml) for cassandra.yaml and the nodetool commands, run (from project root):
 ```bash
 ant gen-asciidoc
 ```

doc/antora.yml

@@ -1,13 +0,0 @@
-name: Cassandra
-version: '5.0'
-display_version: '5.0'
-asciidoc:
-  attributes:
-    cass_url: 'http://cassandra.apache.org/'
-    cass-50: 'Cassandra 5.0'
-    cassandra: 'Cassandra' 
-    product: 'Apache Cassandra'
-
-nav:
-- modules/ROOT/nav.adoc
-- modules/cassandra/nav.adoc

doc/scripts/gen-antora-yml.py

@@ -0,0 +1,93 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+A script to generate doc/antora.yml from build metadata.
+"""
+import os
+import subprocess
+import re
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+def get_version_from_build_xml():
+    build_xml_path = os.path.join(os.path.dirname(os.path.dirname(script_dir)), 'build.xml')
+    
+    try:
+        with open(build_xml_path, 'r') as f:
+            content = f.read()
+        
+        match = re.search(r'<property\s+name="base\.version"\s+value="([^"]+)"', content)
+        if match:
+            return match.group(1)
+        
+        raise ValueError("Could not find base.version property in build.xml")
+    except Exception as e:
+        raise RuntimeError(f"Failed to parse build.xml: {e}")
+
+def is_release_build():
+    """
+    Detect if we're building from a release tag by checking if HEAD has a tag starting with 'cassandra-'.
+    """
+    try:
+        result = subprocess.run(
+            ['git', 'describe', '--tags', '--exact-match'],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        if result.returncode == 0:
+            tag = result.stdout.strip()
+            return tag.startswith('cassandra-')
+        return False
+    except Exception:
+        # If git is not available or any error occurs, assume release build
+        return True
+
+def main():
+    version = get_version_from_build_xml()
+    
+    is_release = is_release_build()    
+    output_path = os.path.join(os.path.dirname(script_dir), 'antora.yml')
+
+    if version.endswith('-SNAPSHOT'):
+        raise ValueError("base.version property in build.xml should not have SNAPSHOT suffix")
+
+    if not is_release:
+        parts = version.split('.')
+        major = parts[0] if len(parts) > 0 else '0'
+        minor = parts[1].split('-')[0] if len(parts) > 1 else '0'
+        version = f"{major}.{minor}"
+
+    with open(output_path, 'w') as f:
+        f.write('# Auto-generated by gen-antora-yml.py\n')
+        f.write('# Do not edit manually - regenerated by `ant gen-asciidoc`\n')
+        f.write(f"name: Cassandra\n")
+        f.write(f"version: '{version}'\n")
+        f.write(f"display_version: '{version}'\n")
+        if not is_release:
+            f.write(f"prerelease: true\n")
+        f.write("asciidoc:\n")
+        f.write("  attributes:\n")
+        f.write(f"    cass_url: http://cassandra.apache.org/\n")
+        f.write(f"    cass-version: Cassandra {version}\n")
+        f.write(f"    cassandra: Cassandra\n")
+        f.write(f"    product: Apache Cassandra\n")
+        f.write("nav:\n")
+        f.write(f"- modules/ROOT/nav.adoc\n")
+        f.write(f"- modules/cassandra/nav.adoc\n")
+
+if __name__ == '__main__':
+    main()