[FLINK-38448] Rework doc build and doc deployment (#1035)

Author: ferenc-csaky

.github/actions/rsync-deployments/action.yml

@@ -0,0 +1,51 @@
+# This implementation took inspiration from https://github.com/Burnett01/rsync-deployments/blob/7.1.0/action.yml
+name: Rsync Deploy (local)
+description: Upload a folder to a single remote destination via rsync over SSH.
+inputs:
+  switches:
+    description: rsync switches
+    required: false
+    default: "--archive --compress"
+  path:
+    description: Local source directory
+    required: true
+  remote_path:
+    description: Remote destination directory
+    required: true
+  remote_host:
+    description: SSH host
+    required: true
+  remote_port:
+    description: SSH port
+    required: false
+    default: "22"
+  remote_user:
+    description: SSH username
+    required: true
+  remote_key:
+    description: SSH private key (OpenSSH/PEM)
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: rsync via ssh-agent
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # Start agent and load the key
+        eval "$(ssh-agent -s)"
+        ssh-add - <<< "${{ inputs.remote_key }}"
+
+        # SSH command with host key checking disabled (matches your reference impl)
+        RSH="ssh -o StrictHostKeyChecking=no -p ${{ inputs.remote_port }}"
+
+        # Resolve paths and DSN
+        LOCAL_PATH="$GITHUB_WORKSPACE/${{ inputs.path }}"
+        DSN="${{ inputs.remote_user }}@${{ inputs.remote_host }}"
+
+        # Deploy
+        sh -c "rsync ${{ inputs.switches }} -e '$RSH' $LOCAL_PATH $DSN:${{ inputs.remote_path }}"
+
+        # Cleanup identities from the agent
+        ssh-add -D || true

.github/workflows/docs.sh

@@ -23,6 +23,9 @@ jobs:
   build-documentation:
     if: github.repository == 'apache/flink-kubernetes-operator'
     runs-on: ubuntu-latest
+    env:
+      HUGO_REPO: https://github.com/gohugoio/hugo/releases/download/v0.104.0/hugo_extended_0.104.0_Linux-64bit.tar.gz
+      HUGO_ARTIFACT: hugo_extended_0.104.0_Linux-64bit.tar.gz
     strategy:
       max-parallel: 1
       matrix:
@@ -31,7 +34,12 @@ jobs:
           - release-1.13
           - release-1.12
     steps:
-      - uses: actions/checkout@v3
+      - name: Set up Temurin JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+      - uses: actions/checkout@v4
         with:
           ref: ${{ matrix.branch }}
       - name: Set branch environment variable
@@ -49,11 +57,37 @@ jobs:
           fi
       - name: Build documentation
         run: |
-          docker run  --rm --volume "$PWD:/root/flink-kubernetes-operator" chesnay/flink-ci:java_8_11 bash -c "cd /root/flink-kubernetes-operator && ./.github/workflows/docs.sh"
+          if ! curl --fail -OL "$HUGO_REPO" ; then
+            echo "Failed to download Hugo binary"
+            exit 1
+          fi
+          tar -zxvf "$HUGO_ARTIFACT"
+          git submodule update --init --recursive
+
+          # generate docs into docs/target
+          ./hugo -v --source docs --destination target
+          if [ $? -ne 0 ]; then
+            echo "Error building the docs"
+            exit 1
+          fi
+
+          # build Java docs
+          mkdir -p docs/target/api
+      
+          mvn javadoc:aggregate -B \
+          -DadditionalJOption="-Xdoclint:none" \
+          -DadditionalJOption="--allow-script-in-comments" \
+          -DexcludePackageNames="org.apache.flink.examples" \
+          -Dmaven.javadoc.failOnError=false \
+          -Dcheckstyle.skip=true \
+          -Dspotless.check.skip=true \
+          -Denforcer.skip=true \
+          -Dheader="<a href=\"http://flink.apache.org/\" target=\"_top\"><h1>Back to Flink Website</h1></a> <script>var _paq=window._paq=window._paq||[];_paq.push([\"disableCookies\"]),_paq.push([\"setDomains\",[\"*.flink.apache.org\",\"*.nightlies.apache.org/flink\"]]),_paq.push([\"trackPageView\"]),_paq.push([\"enableLinkTracking\"]),function(){var u=\"//matomo.privacy.apache.org/\";_paq.push([\"setTrackerUrl\",u+\"matomo.php\"]),_paq.push([\"setSiteId\",\"1\"]);var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s)}();</script>"
+      
+          mv target/site/apidocs docs/target/api/java
       - name: Upload documentation
-        uses: burnett01/rsync-deployments@5.2
+        uses: ./.github/actions/rsync-deployments
         with:
-          switches: --archive --compress
           path: docs/target/
           remote_path: ${{ secrets.NIGHTLIES_RSYNC_PATH }}/flink/flink-kubernetes-operator-docs-${{ env.flink_branch }}/
           remote_host: ${{ secrets.NIGHTLIES_RSYNC_HOST }}
@@ -62,9 +96,8 @@ jobs:
           remote_key: ${{ secrets.NIGHTLIES_RSYNC_KEY }}
       - name: Upload documentation alias
         if: env.flink_alias != ''
-        uses: burnett01/rsync-deployments@5.2
+        uses: ./.github/actions/rsync-deployments
         with:
-          switches: --archive --compress
           path: docs/target/
           remote_path: ${{ secrets.NIGHTLIES_RSYNC_PATH }}/flink/flink-kubernetes-operator-docs-${{ env.flink_alias }}/
           remote_host: ${{ secrets.NIGHTLIES_RSYNC_HOST }}

.github/workflows/docs.yaml

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019-2022 Contention
+Copyright (c) 2019-2025 Burnett01
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.