JavaDoc as HTML and JARs

.github/workflows/build.yaml

@@ -83,7 +83,8 @@ jobs:
         # we need to use install here because otherwise the code checks below don't work
         # they require the JARs of all modules to work, so those need to be installed
         run: |
-          mvn $MVN_CLI_ARGS install -DskipTests -DskipFormatting
+          python .pipeline/scripts/generate-javadoc-sourcepath-properties.py
+          mvn $MVN_CLI_ARGS install -DskipTests -DskipFormatting -Pdocs
           python .pipeline/scripts/generate-release-artifacts.py --version ${{ steps.get-version.outputs.VERSION }} --path-prefix release
           zip -q -r sap-cloud-sdk-java-${{ steps.get-version.outputs.VERSION }}.zip release
           rm -rf release

.github/workflows/perform_release.yml

@@ -4,6 +4,14 @@ on:
   release:
     types: [published]
 
+#  # Uncomment the following lines to enable manual workflow trigger
+#  # Make sure to swap out the two places referencing GIT_TAG in the steps below
+#  workflow_dispatch:
+#    inputs:
+#      release_version:
+#        description: "Release version, leave empty for default value based on current snapshot"
+#        required: false
+
 env:
   MVN_CLI_ARGS: "--batch-mode --no-transfer-progress --fail-at-end --show-version"
 
@@ -29,6 +37,8 @@ jobs:
         id: download-asset
         run: |
           GIT_TAG=${{ github.event.release.tag_name }}
+          # When enabling the manual workflow trigger, use the next line instead of the previous one
+          # GIT_TAG=rel/${{ github.event.inputs.release_version }}
           echo Git Tag "$GIT_TAG"
 
           BRANCH_NAME=`python -c "print('RELEASE-' + '$GIT_TAG'.replace('rel/', ''))"`
@@ -37,6 +47,7 @@ jobs:
 
           gh release download "$GIT_TAG" --dir ./ --repo "SAP/cloud-sdk-java"
           unzip sap-cloud-sdk-java-*.zip -d .
+          unzip sap-cloud-sdk-aggregated-javadoc-*.zip -d .
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -54,12 +65,80 @@ jobs:
           ARTIFACTORY_USER: ${{ secrets.ARTIFACTORY_USER }}
           ARTIFACTORY_TOKEN: ${{ secrets.ARTIFACTORY_TOKEN }}
 
+      - name: Get SDK Major Version
+        run: |
+          echo "VERSION=$(echo $GIT_TAG | awk -F'/' '{print $2}')" >> $GITHUB_ENV
+          echo "MAJOR_VERSION=$(echo $GIT_TAG | awk -F'/' '{print $2}' | awk -F'.' '{print $1}')" >> $GITHUB_ENV
+        env:
+          GIT_TAG: ${{ github.event.release.tag_name }}
+          # When enabling the manual workflow trigger, use the next line instead of the previous one
+          # GIT_TAG: rel/${{ github.event.inputs.release_version }}
+
+      - name: Checkout SAP/cloud-sdk
+        uses: actions/checkout@v3
+        with:
+          repository: SAP/cloud-sdk
+          path: cloud-sdk
+          token: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}
+
+      - name: Prepare git
+        working-directory: ./cloud-sdk
+        run: |
+          git config --global user.email "cloudsdk@sap.com"
+          git config --global user.name "SAP Cloud SDK Bot"
+
+      - name: Replace JavaDoc in new Branch
+        working-directory: ./cloud-sdk
+        env:
+          MAJOR_VERSION: ${{ env.MAJOR_VERSION }}
+          VERSION: ${{ env.VERSION }}
+        run: |
+          TARGET_DIR=static/java-api/v$MAJOR_VERSION
+          rm -rf $TARGET_DIR
+          mkdir -p $TARGET_DIR
+          mv ../sap-cloud-sdk-aggregated-javadoc/* $TARGET_DIR
+
+          git add -A $TARGET_DIR
+
+          CHANGED_FILES="$(git status -s)"
+          if [ -z "$CHANGED_FILES" ]; then
+              echo "No changes to API docs detected, skipping Pull Request creation."
+              echo "CREATE_PR=false" >> $GITHUB_ENV
+              exit 0
+          fi
+
+          echo "CREATE_PR=true" >> $GITHUB_ENV
+
+          CLOUD_SDK_BRANCH_NAME=update-java-api-docs-v$VERSION
+          echo "CLOUD_SDK_BRANCH_NAME=$CLOUD_SDK_BRANCH_NAME" >> $GITHUB_ENV
+
+          git switch --create $CLOUD_SDK_BRANCH_NAME
+
+          git commit -m "Update SAP Cloud SDK for Java API docs for v$MAJOR_VERSION"
+
+          git push origin $CLOUD_SDK_BRANCH_NAME:$CLOUD_SDK_BRANCH_NAME
+
+      - name: Create JavaDoc PR
+        if: ${{ env.CREATE_PR == 'true' }}
+        working-directory: ./cloud-sdk
+        run: |
+          PR_TITLE="Update SAP Cloud SDK for Java API docs for v$MAJOR_VERSION"
+          PR_BODY="Replace the contents of v$MAJOR_VERSION API docs with the latest release of the SDK."
+
+          gh pr create --title "$PR_TITLE" --body "$PR_BODY" --repo "SAP/cloud-sdk"
+        env:
+          MAJOR_VERSION: ${{ env.MAJOR_VERSION }}
+          VERSION: ${{ env.VERSION }}
+          GH_TOKEN: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}
+
       - name: Merge Release Branch
-        run: gh pr merge --rebase "${{ steps.download-asset.outputs.BRANCH_NAME }}" --repo "SAP/cloud-sdk-java"
+        run: gh pr merge --squash "${{ steps.download-asset.outputs.BRANCH_NAME }}" --repo "SAP/cloud-sdk-java"
+        env:
+          GH_TOKEN: ${{ github.token }}
 
   notify-job:
     runs-on: ubuntu-latest
-    needs: [ release ]
+    needs: [release]
     if: ${{ failure() }}
     steps:
       - name: Checkout

.github/workflows/prepare_release.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
         with:
-          ref: 'main'
+          ref: ${{ github.event.repository.default_branch }}
 
       - name: Setup java
         uses: actions/setup-java@v3
@@ -89,7 +89,8 @@ jobs:
           java-version: 17
       - name: Test and Package
         run: |
-          mvn $MVN_CLI_ARGS install jacoco:report
+          python .pipeline/scripts/generate-javadoc-sourcepath-properties.py
+          mvn $MVN_CLI_ARGS install jacoco:report javadoc:aggregate -Pdocs
           python .pipeline/scripts/generate-release-artifacts.py --version ${{ needs.prepare-release.outputs.release_version }} --path-prefix release
           zip -q -r sap-cloud-sdk-java-${{ needs.prepare-release.outputs.release_version }}.zip release
       - name: Local Changes Check
@@ -123,6 +124,11 @@ jobs:
           name: cloud-sdk-package
           path: sap-cloud-sdk-java-${{ needs.prepare-release.outputs.release_version }}.zip
           retention-days: 1
+      - name: Upload JavaDocs
+        uses: actions/upload-artifact@v3
+        with:
+          name: cloud-sdk-aggregated-javadoc
+          path: ./target/site/apidocs
 
   archetypes:
     runs-on: ubuntu-latest
@@ -136,7 +142,7 @@ jobs:
           - {
               "archetype": "scp-cf-spring",
               "javaVersion": 8,
-              "startCommand": "mvn spring-boot:run -B"
+              "startCommand": "mvn spring-boot:run -B",
             }
           - {
               "archetype": "scp-cf-spring-jakarta",
@@ -367,21 +373,37 @@ jobs:
           name: cloud-sdk-package
           path: .
 
+      - name: Download JavaDocs
+        uses: actions/download-artifact@v3
+        with:
+          name: cloud-sdk-aggregated-javadoc
+          path: ./sap-cloud-sdk-aggregated-javadoc
+
+      - name: Zip JavaDocs for Release
+        run: |
+          zip -q -r sap-cloud-sdk-aggregated-javadoc-${{ needs.prepare-release.outputs.release_version }}.zip sap-cloud-sdk-aggregated-javadoc
+          rm -rf sap-cloud-sdk-aggregated-javadoc
+
       - name: Prepare git
         run: |
           git config --global user.email "noreply+s4hana-cloud-sdk@sap.com"
           git config --global user.name "Maven Central Release Script"
 
       - name: Create release
         run: |
-          gh release create "rel/${{ needs.prepare-release.outputs.release_version }}" \
-            --target ${{ needs.prepare-release.outputs.release_commit_id }} \
-            --title "Release ${{ needs.prepare-release.outputs.release_version }}" \
-            --draft --generate-notes sap-cloud-sdk-java-${{ needs.prepare-release.outputs.release_version }}.zip
-
-          rm -rf sap-cloud-sdk-java-${{ needs.prepare-release.outputs.release_version }}.zip
+          gh release create "rel/$VERSION" \
+            --target $COMMIT_ID \
+            --title "Release $VERSION" \
+            --draft --generate-notes \
+            sap-cloud-sdk-java-$VERSION.zip \
+            sap-cloud-sdk-aggregated-javadoc-$VERSION.zip
+
+          rm -rf sap-cloud-sdk-java-$VERSION.zip
+          rm -rf sap-cloud-sdk-aggregated-javadoc-$VERSION.zip
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.prepare-release.outputs.release_version }}
+          COMMIT_ID: ${{ needs.prepare-release.outputs.release_commit_id }}
 
       - name: Set new snapshot version
         run: |
@@ -392,16 +414,27 @@ jobs:
 
       - name: Create PR
         run: |
-          RELEASE_URL=$(gh release view rel/${{ needs.prepare-release.outputs.release_version }} --json url | jq -r .url)
-          PR_BODY=$(python .pipeline/scripts/print-pr-body.py --commit-url https://github.com/SAP/cloud-sdk-java/commit/${{ needs.prepare-release.outputs.release_commit_id }} --release-url $RELEASE_URL)
+          RELEASE_URL=$(gh release view rel/$VERSION --json url | jq -r .url)
+          PR_BODY=$(python .pipeline/scripts/print-pr-body.py --commit-url https://github.com/SAP/cloud-sdk-java/commit/$COMMIT_ID --release-url $RELEASE_URL)
 
-          gh pr create --title "Release ${{ needs.prepare-release.outputs.release_version }}" \
-             --body "$PR_BODY"
+          gh pr create --title "Release $VERSION" --body "$PR_BODY"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.prepare-release.outputs.release_version }}
+          COMMIT_ID: ${{ needs.prepare-release.outputs.release_commit_id }}
+
   notify-job:
     runs-on: ubuntu-latest
-    needs: [prepare-release, build, archetypes, codeql, create-release, scan, create_fosstars_report]
+    needs:
+      [
+        prepare-release,
+        build,
+        archetypes,
+        codeql,
+        create-release,
+        scan,
+        create_fosstars_report,
+      ]
     if: ${{ failure() }}
     steps:
       - name: Checkout

.gitignore

@@ -44,6 +44,7 @@ scripts/usageanalytics/figures/*.pdf
 .mvn
 **/.factorypath
 mvnvm.properties
+javadoc.properties
 
 **/.openapi-generator/**
 

.pipeline/scripts/generate-javadoc-sourcepath-properties.py

@@ -0,0 +1,26 @@
+import json
+
+
+def write_javadoc_sourcepath_properties():
+    with open("module-inventory.json", "r") as file:
+        module_inventory = json.load(file)
+
+        with open("javadoc.properties", "w") as output:
+            output.write("javadoc.sourcepath = ")
+
+            for i, module in enumerate(module_inventory, start=1):
+                if module["releaseAudience"] != "Public":
+                    continue
+                target_path = module["pomFile"].replace("pom.xml", "target/delombok;")
+                if i == len(module_inventory):
+                    output.write(target_path)
+                else:
+                    output.write(target_path + "\\\n")
+
+
+def main():
+    write_javadoc_sourcepath_properties()
+
+
+if __name__ == '__main__':
+    main()

.pipeline/scripts/generate-release-artifacts.py

@@ -38,26 +38,28 @@
 """
 
 pom_end = """
-                </executions>
-            </plugin>
         </plugins>
     </build>
 </project>
 """
 
+
 def sanitize_path(*args):
     return os.path.normpath(os.path.join(*args))
 
+
 def to_maven_path(*args):
     return sanitize_path(*args).replace("\\", "/")
 
+
 def get_module_source_path(module):
     return module["pomFile"].replace("pom.xml", "target")
 
 
 def get_module_dest_path(module):
     return sanitize_path("artifacts", module["pomFile"].replace("pom.xml", ""))
 
+
 def copy_artifacts(path_prefix, sdk_version):
     with open("module-inventory.json", "r") as file:
         module_inventory = json.load(file)
@@ -78,11 +80,28 @@ def copy_artifacts(path_prefix, sdk_version):
                 dst_artifact = sanitize_path(dst_path, module["artifactId"] + "-" + sdk_version + ".jar")
                 shutil.copyfile(src_artifact, dst_artifact)
 
-def generate_execution(phase, module, sdk_version):
+                src_docs_artifact = sanitize_path(src_path, module["artifactId"] + "-" + sdk_version + "-javadoc.jar")
+                if os.path.exists(src_docs_artifact):
+                    dst_docs_artifact = sanitize_path(dst_path, module["artifactId"] + "-" + sdk_version + "-javadoc.jar")
+                    shutil.copyfile(src_docs_artifact, dst_docs_artifact)
+
+                src_sources_artifact = sanitize_path(src_path, module["artifactId"] + "-" + sdk_version + "-sources.jar")
+                if os.path.exists(src_sources_artifact):
+                    dst_sources_artifact = sanitize_path(dst_path, module["artifactId"] + "-" + sdk_version + "-sources.jar")
+                    shutil.copyfile(src_sources_artifact, dst_sources_artifact)
+
+
+def generate_execution(path_prefix, phase, module, sdk_version):
     artifact_path = to_maven_path(get_module_dest_path(module), module["artifactId"] + "-" + sdk_version)
     file = artifact_path + "." + module["packaging"]
     pom_path = to_maven_path("artifacts", module["pomFile"])
     packaging = module["packaging"]
+    sources = artifact_path + "-sources.jar"
+    if not os.path.exists(sanitize_path(path_prefix, sources)):
+        sources = ""
+    javadoc = artifact_path + "-javadoc.jar"
+    if not os.path.exists(sanitize_path(path_prefix, javadoc)):
+        javadoc = ""
     if module["packaging"] == "pom":
         file = pom_path
     elif module["packaging"] == "maven-archetype" or module["packaging"] == "maven-plugin":
@@ -98,6 +117,8 @@ def generate_execution(phase, module, sdk_version):
                       </goals>
                       <configuration>
                           <file>{file}</file>
+                          <sources>{sources}</sources>
+                          <javadoc>{javadoc}</javadoc>
                           <pomFile>{pom_path}</pomFile>
                           <groupId>{module["groupId"]}</groupId>
                           <artifactId>{module["artifactId"]}</artifactId>
@@ -107,27 +128,29 @@ def generate_execution(phase, module, sdk_version):
                   </execution>
                 """
 
+
 def generate_pom(path_prefix, sdk_version):
     with open("module-inventory.json", "r") as file:
         module_inventory = json.load(file)
 
         with open(sanitize_path(path_prefix, "pom.xml"), "w") as f:
             f.write(pom_beginning.replace("${sdkVersion}", sdk_version))
-            f.write(pom_begin_install_plugin)
 
+            f.write(pom_begin_install_plugin)
             for module in module_inventory:
-                if module["releaseAudience"] != "Public":
-                    continue
-                f.write(generate_execution("install", module, sdk_version))
+                if module["releaseAudience"] == "Public":
+                    f.write(generate_execution(path_prefix, "install", module, sdk_version))
             f.write(pom_end_plugin)
 
             f.write(pom_begin_deploy_plugin)
             for module in module_inventory:
-                if module["releaseAudience"] != "Public":
-                    continue
-                f.write(generate_execution("deploy", module, sdk_version))
+                if module["releaseAudience"] == "Public":
+                    f.write(generate_execution(path_prefix, "deploy", module, sdk_version))
+            f.write(pom_end_plugin)
+
             f.write(pom_end)
 
+
 def main():
     parser: argparse.ArgumentParser = argparse.ArgumentParser(
         description="Iterates the module inventory and generates a pom.xml file for installing or deploying all "