(kafka) branch trunk updated: KAFKA-21289 Fix release.py stage-docs for Hugo kafka-site (#23833)

[ch...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

chia7712 pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 59046aecc31 KAFKA-21289 Fix release.py stage-docs for Hugo kafka-site (#23833)
59046aecc31 is described below

commit 59046aecc31bd1bed83a434c0db61aea95fd644a
Author: Omnia Ibrahim <o....@gmail.com>
AuthorDate: Fri Oct 16 18:14:47 2026 +0100

    KAFKA-21289 Fix release.py stage-docs for Hugo kafka-site (#23833)
    
    Changes
    
    - swaps the sentinel check to `hugo.yaml` instead of `owered-by.html`
    - splits the extraction: markdown goes to `content/en/<version>`,
    javadoc goes to `static/<version>`
    - the site-docs tar bundles images in alongside the markdown, so those
    get pulled out of `content/en/<version>/images` and moved into
    `static/<version>/images` right after extraction — otherwise they’d sit
    in the wrong place. NOTE: I hardcoded `images` as the one directory that
    needs pulling out of `content/<version>` — based on what’s actually in
    the tar now and what the existing slots look like. Any future doc change
    bundling some other asset directory into the tar won’t be caught by
    this.
    
    - fixed a small pre-existing bug while I was in there: the sentinel
    failure message was missing an `f` prefix, so it was printing
    `{kafka_site_repo_path}` literally instead of the actual path
    
    Testing
    - Ran stage-docs locally twice against `4.4.0`, staged into a real
    Hugo-based kafka-site clone. `content/en/44` and `static/44` come out
    matching exactly what the `4.0`, `4.3.0`, and `4.3.1` slots already look
    like — same top-level structure. `4.4.0` docs are published as part of
    [kafka-site#925](https://github.com/apache/kafka-site/pull/925 )
    
    Reviewers: Chia-Ping Tsai <ch...@gmail.com>
---
 release/release.py | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/release/release.py b/release/release.py
index 6014f4f8f65..2d8b84910b2 100644
--- a/release/release.py
+++ b/release/release.py
@@ -125,8 +125,8 @@ def detect_docs_release_version(version):
 
 def command_stage_docs():
     kafka_site_repo_path = sys.argv[2] if len(sys.argv) > 2 else os.path.join(repo_dir, "..", "kafka-site")
-    if not os.path.exists(kafka_site_repo_path) or not os.path.exists(os.path.join(kafka_site_repo_path, "powered-by.html")):
-        fail("{kafka_site_repo_path} doesn't exist or does not appear to be the kafka-site repository")
+    if not os.path.exists(kafka_site_repo_path) or not os.path.exists(os.path.join(kafka_site_repo_path, "hugo.yaml")):
+        fail(f"{kafka_site_repo_path} doesn't exist or does not appear to be the kafka-site repository")
 
     jdk25_env = get_jdk(25)
 
@@ -139,20 +139,32 @@ def command_stage_docs():
     # Disable parallel execution for aggregatedJavadoc due to Gradle 9 issues
     cmd("Building docs", f"./gradlew -Pversion={gradle_version_override} aggregatedJavadoc --no-parallel", cwd=repo_dir, env=jdk25_env,)
 
-
     docs_tar = os.path.join(repo_dir, "core", "build", "distributions", f"kafka_2.13-{gradle_version_override}-site-docs.tgz")
 
-    versioned_docs_path = os.path.join(kafka_site_repo_path, docs_version(project_version))
-    if not os.path.exists(versioned_docs_path):
-        os.mkdir(versioned_docs_path, 0o755)
+    # Hugo layout: markdown/content pages live under content/en/<version>,
+    # javadoc and other static assets live under static/<version>
+    docs_slot = docs_version(project_version)
+    content_docs_path = os.path.join(kafka_site_repo_path, "content", "en", docs_slot)
+    static_docs_path = os.path.join(kafka_site_repo_path, "static", docs_slot)
+    if not os.path.exists(content_docs_path):
+        os.makedirs(content_docs_path, 0o755)
+    if not os.path.exists(static_docs_path):
+        os.makedirs(static_docs_path, 0o755)
 
     # The contents of the docs jar are site-docs/<docs dir>. We need to get rid of the site-docs prefix and dump everything
     # inside it into the docs version subdirectory in the kafka-site repo
-    cmd("Extracting site-docs", f"tar xf {docs_tar} --strip-components 1", cwd=versioned_docs_path)
+    cmd("Extracting site-docs", f"tar xf {docs_tar} --strip-components 1", cwd=content_docs_path)
+
+    # Images come bundled in the tar, but belong under static/<version>, not
+    # content/en/<version>. Move them out after extraction.
+    content_images_path = os.path.join(content_docs_path, "images")
+    if os.path.exists(content_images_path):
+        static_images_path = os.path.join(static_docs_path, "images")
+        cmd("Moving images to static assets", f"mkdir -p {static_images_path} && cp -R {content_images_path}/. {static_images_path} && rm -rf {content_images_path}", shell=True)
 
     javadocs_src_dir = os.path.join(repo_dir, "build", "docs", "javadoc")
 
-    cmd("Copying javadocs", f"cp -R {javadocs_src_dir} {versioned_docs_path}")
+    cmd("Copying javadocs", f"cp -R {javadocs_src_dir} {static_docs_path}")
 
     sys.exit(0)