[FLINK-38448] Rework doc build and doc deployment (#1035)
diff --git a/.github/actions/rsync-deployments/action.yml b/.github/actions/rsync-deployments/action.yml
new file mode 100644
index 0000000..e1f2c5e
--- /dev/null
+++ b/.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
diff --git a/.github/workflows/docs.sh b/.github/workflows/docs.sh
deleted file mode 100755
index 079535d..0000000
--- a/.github/workflows/docs.sh
+++ /dev/null
@@ -1,53 +0,0 @@
-#!/usr/bin/env bash
-################################################################################
-# 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.
-################################################################################
-set -e
-
-export JAVA_HOME=$JAVA_HOME_11_X64
-
-# setup hugo
-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
-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 Flink Operator; required for Javadoc step
-#mvn clean install -B -DskipTests
-
-# 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
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 59c38d6..20432be 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -23,6 +23,9 @@
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 @@
- 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 @@
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 @@
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 }}
diff --git a/LICENSE.rsync-deployments b/LICENSE.rsync-deployments
new file mode 100644
index 0000000..aa38d49
--- /dev/null
+++ b/LICENSE.rsync-deployments
@@ -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.
