-
Notifications
You must be signed in to change notification settings - Fork 20
feat: automated javadoc generation with artifact upload #844
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+335
−1
Merged
Changes from all commits
Commits
Show all changes
39 commits
Select commit
Hold shift + click to select a range
95b8269
trial 1
n-o-u-r-h-a-n 57a56ab
Merge branch 'main' into fixing-javadoc
n-o-u-r-h-a-n fb0c156
revert
n-o-u-r-h-a-n 251f09d
Approach 1
n-o-u-r-h-a-n 3d708cd
Merge branch 'main' into fixing-javadoc
n-o-u-r-h-a-n fff1443
Approach 2
n-o-u-r-h-a-n beb1cdb
Approach 2- fix
n-o-u-r-h-a-n 35ef33f
Approach 2- fix-2
n-o-u-r-h-a-n 7e9bea0
Approach 2- fix-3
n-o-u-r-h-a-n 9e46505
Approach 2- fix-4
n-o-u-r-h-a-n 07708dc
Approach 2- fix-5
n-o-u-r-h-a-n f9266a5
doing the call inside prepare-release.yaml
n-o-u-r-h-a-n d5cb9a1
doing the call inside prepare-release.yaml
n-o-u-r-h-a-n d8d41ca
trial 3
n-o-u-r-h-a-n a7c9a7d
Merge branch 'main' into fixing-javadoc
n-o-u-r-h-a-n 9707942
revert prepare-release integration
n-o-u-r-h-a-n b636e0c
testing in CI workflow
n-o-u-r-h-a-n 183ec12
testing in CI workflow-1
n-o-u-r-h-a-n aef90cb
testing in CI workflow-2
n-o-u-r-h-a-n 8f0fb3d
testing in CI workflow-3
n-o-u-r-h-a-n 5b3fa58
revert
n-o-u-r-h-a-n 5893a21
reverting pom
n-o-u-r-h-a-n d0fc5b7
2nd approach
n-o-u-r-h-a-n f771d38
reverted CI
n-o-u-r-h-a-n 0bd22fb
Update .github/workflows/javadoc.yaml
n-o-u-r-h-a-n 75eb668
fix minor comments
n-o-u-r-h-a-n 9de658d
Merge remote-tracking branch 'origin/fixing-javadoc' into fixing-javadoc
n-o-u-r-h-a-n 252bf87
fix major issue
n-o-u-r-h-a-n 4dfafcb
additional fixes
n-o-u-r-h-a-n 8bbf930
adding comments
n-o-u-r-h-a-n 218cfc4
Merge branch 'main' into fixing-javadoc
n-o-u-r-h-a-n b5ec6ad
automating the javadocs
n-o-u-r-h-a-n 899edc6
adding permission
n-o-u-r-h-a-n f3062d2
Potential fix for pull request finding 'CodeQL / Workflow does not co…
n-o-u-r-h-a-n 933fe1b
formatting
n-o-u-r-h-a-n 24806ed
Update .github/workflows/javadoc.yaml
n-o-u-r-h-a-n 82ed079
Update .github/workflows/javadoc.yaml
n-o-u-r-h-a-n 5243285
release notes
n-o-u-r-h-a-n ceb5f6f
Merge remote-tracking branch 'origin/fixing-javadoc' into fixing-javadoc
n-o-u-r-h-a-n File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,292 @@ | ||
| name: JavaDoc to Documentation Portal | ||
| on: | ||
| workflow_dispatch: | ||
| inputs: | ||
| branch: | ||
| description: 'Branch/Commit/Tag for JavaDoc' | ||
| required: true | ||
| default: 'main' | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| env: | ||
| JAVA_VERSION: 21 | ||
| MAVEN_CACHE_KEY: maven-dependencies | ||
| MAVEN_CACHE_DIR: ~/.m2 | ||
| DOCS_REPO: SAP/ai-sdk | ||
| MODULE_PATHS: | | ||
| core | ||
| orchestration | ||
| core-services/document-grounding | ||
| core-services/prompt-registry | ||
| foundation-models/openai | ||
| foundation-models/sap-rpt | ||
| MODULE_NAMES: | | ||
| AI Core client | ||
| Orchestration client | ||
| Document Grounding Client | ||
| Prompt Registry client | ||
| OpenAI client | ||
| SAP RPT Model Client | ||
|
|
||
| jobs: | ||
|
|
||
| build: | ||
| runs-on: ubuntu-latest | ||
| defaults: | ||
| run: | ||
| shell: bash -euo pipefail {0} | ||
| steps: | ||
|
|
||
| - name: "Checkout repository" | ||
| uses: actions/checkout@v6 | ||
| with: | ||
| fetch-depth: 1 | ||
| ref: ${{ inputs.branch }} | ||
|
|
||
| - name: "Setup Java" | ||
| uses: actions/setup-java@v5 | ||
| with: | ||
| distribution: "sapmachine" | ||
| java-version: ${{ env.JAVA_VERSION }} | ||
| cache: 'maven' | ||
|
|
||
| - name: "Restore Dependencies" | ||
| uses: actions/cache/restore@v5 | ||
| with: | ||
| key: ${{ env.MAVEN_CACHE_KEY }} | ||
| path: ${{ env.MAVEN_CACHE_DIR }} | ||
|
|
||
| - name: "Build SDK" | ||
| run: > | ||
| mvn -B -ntp -Dstyle.color=never -Drelease -DskipTests -Dgpg.skip=true | ||
| clean install | ||
|
|
||
| - name: "Generate Javadocs from delomboked sources" | ||
| run: | | ||
| JAVADOC="$JAVA_HOME/bin/javadoc" | ||
|
|
||
| # Reconstruct the module list from the top-level env var. | ||
| # printf '%s' prevents <<< from adding an extra newline, which would produce a spurious empty element. | ||
| readarray -t module_paths < <(printf '%s' "$MODULE_PATHS") | ||
|
|
||
| # Build a classpath from all module JARs and their dependencies so javadoc can resolve cross-module type references. | ||
| classpath="" | ||
| for module_path in "${module_paths[@]}"; do | ||
| cp_file="$module_path/target/cp.txt" | ||
|
|
||
| # Write all compile- and provided-scope dependency JARs to cp.txt. | ||
| # provided-scope types (e.g. SAP Cloud SDK interfaces) must be on the classpath for javadoc to resolve them. | ||
| mvn -B -ntp -f "$module_path/pom.xml" \ | ||
| dependency:build-classpath -Dmdep.outputFile=target/cp.txt -Dmdep.includeScope=provided \ | ||
| -Dgpg.skip=true -q | ||
|
|
||
| # Add the module's own compiled JAR to the classpath. | ||
| # Exclude *-sources.jar and *-javadoc.jar produced by the release profile. | ||
| module_jar=$(find "$module_path/target" -maxdepth 1 -name "*.jar" ! -name "*sources*" ! -name "*javadoc*" | head -1) | ||
| if [[ -n "$module_jar" ]]; then | ||
| [[ -z "$classpath" ]] && classpath="$module_jar" || classpath+=":$module_jar" | ||
| fi | ||
|
|
||
| # Append the dependency JARs from cp.txt to the classpath. | ||
| if [[ -f "$cp_file" ]]; then | ||
| cp_content=$(cat "$cp_file") | ||
| if [[ -n "$cp_content" ]]; then | ||
| [[ -z "$classpath" ]] && classpath="$cp_content" || classpath+=":$cp_content" | ||
| fi | ||
| fi | ||
| done | ||
|
|
||
| # Runs the javadoc tool for a given source tree and writes HTML to destdir. | ||
| run_javadoc() { | ||
| local javadoc="$1" | ||
| local sourcepath="$2" | ||
| local destdir="$3" | ||
| local pkg_file="$4" | ||
| local cp="$5" | ||
|
|
||
| # Skip if no packages were found for this module. | ||
| if [[ ! -s "$pkg_file" ]]; then | ||
| echo "No packages found for $destdir, skipping" >&2 | ||
| return | ||
| fi | ||
|
|
||
| mkdir -p "$destdir" | ||
| "$javadoc" \ | ||
| -sourcepath "$sourcepath" \ | ||
| -d "$destdir" \ | ||
| -classpath "$cp" \ | ||
| -quiet \ | ||
| -Xdoclint:none \ | ||
| -encoding UTF-8 \ | ||
| -charset UTF-8 \ | ||
| -docencoding UTF-8 \ | ||
| @"$pkg_file" | ||
| } | ||
|
|
||
| # Generate per-module javadocs from delomboked sources (Lombok annotations expanded to plain Java). | ||
| for module_path in "${module_paths[@]}"; do | ||
| delombok_dir="$module_path/target/delombok" | ||
| if [[ ! -d "$delombok_dir" ]]; then | ||
| echo "Missing delombok sources for $module_path" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Extract unique package names from the module's Java files. | ||
| # -print0/-0: null-delimited to handle spaces in paths; -r: skip if no files; -h: omit filenames from output. | ||
| pkg_file="$module_path/target/javadoc-packages" | ||
| find "$delombok_dir" -name "*.java" -print0 \ | ||
| | xargs -r -0 grep -h "^package " \ | ||
| | awk '{print $2}' | tr -d ';' | sort -u > "$pkg_file" | ||
| echo "Generating javadoc for $module_path ..." | ||
| run_javadoc "$JAVADOC" "$delombok_dir" "$module_path/target/javadoc-delombok" "$pkg_file" "$classpath" | ||
| done | ||
|
|
||
| # Generate a combined javadoc across all modules with a unified package index. | ||
| combined_sourcepath="" | ||
| combined_pkg_file="target/javadoc-all-packages" | ||
| > "$combined_pkg_file" | ||
| for module_path in "${module_paths[@]}"; do | ||
| delombok_dir="$module_path/target/delombok" | ||
| # Colon-join all delombok dirs into a single sourcepath for javadoc. | ||
| [[ -z "$combined_sourcepath" ]] \ | ||
| && combined_sourcepath="$delombok_dir" \ | ||
| || combined_sourcepath+=":$delombok_dir" | ||
| # Accumulate package names from all modules into one file. | ||
| cat "$module_path/target/javadoc-packages" >> "$combined_pkg_file" | ||
| done | ||
| # Deduplicate packages shared across modules. | ||
| sort -u "$combined_pkg_file" -o "$combined_pkg_file" | ||
| echo "Generating combined javadoc for sdk-parent ..." | ||
| run_javadoc "$JAVADOC" "$combined_sourcepath" "target/javadoc-delombok" "$combined_pkg_file" "$classpath" | ||
|
|
||
| - name: "Assemble local-javadocs output directory" | ||
| run: | | ||
| out_dir="target/local-javadocs" | ||
| rm -rf "$out_dir" | ||
| mkdir -p "$out_dir" | ||
|
|
||
| # Reconstruct the module lists from the top-level env vars. | ||
| # printf '%s' prevents <<< from adding an extra newline, which would produce a spurious empty element. | ||
| readarray -t module_paths < <(printf '%s' "$MODULE_PATHS") | ||
| readarray -t module_names < <(printf '%s' "$MODULE_NAMES") | ||
|
|
||
| # Copy the combined javadoc into the 'aggregate' subdirectory. | ||
| if [[ ! -f "target/javadoc-delombok/index.html" ]]; then | ||
| echo "Missing combined javadocs at target/javadoc-delombok" >&2 | ||
| exit 1 | ||
| fi | ||
| cp -R "target/javadoc-delombok" "$out_dir/aggregate" | ||
|
|
||
| # Write an HTML index linking to the aggregate docs and each per-module doc. | ||
| index_file="$out_dir/index.html" | ||
| cat > "$index_file" <<'HTML' | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <title>Local Javadocs</title> | ||
| </head> | ||
| <body> | ||
| <h1>Local Javadocs</h1> | ||
| <p><a href="aggregate/index.html">Aggregate API docs (all modules)</a></p> | ||
| <ul> | ||
| HTML | ||
|
|
||
| # Iterate over modules by index to pair each path with its display name. | ||
| for i in "${!module_paths[@]}"; do | ||
| module_path="${module_paths[$i]}" | ||
| module_name="${module_names[$i]}" | ||
| # Replace '/' with '-' to use the module path as a flat directory name. | ||
| module_id="${module_path//\//-}" | ||
|
|
||
| src_dir="$module_path/target/javadoc-delombok" | ||
| if [[ ! -f "$src_dir/index.html" ]]; then | ||
| echo "Missing javadocs for $module_path at $src_dir" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Copy the module's javadoc into the output dir and add an index entry. | ||
| cp -R "$src_dir" "$out_dir/$module_id" | ||
| printf ' <li><a href="%s/index.html">%s</a></li>\n' "$module_id" "$module_name" >> "$index_file" | ||
| done | ||
|
|
||
| cat >> "$index_file" <<'HTML' | ||
| </ul> | ||
| </body> | ||
| </html> | ||
| HTML | ||
|
|
||
| echo "Local javadocs assembled at: $out_dir/index.html" | ||
|
|
||
| - name: "Upload Javadocs artifact" | ||
| uses: actions/upload-artifact@v7 | ||
| with: | ||
| name: local-javadocs | ||
| path: target/local-javadocs/ | ||
| retention-days: 7 | ||
|
|
||
| - name: "Determine Version" | ||
| id: determine-version | ||
| run: | | ||
| VERSION="${{ inputs.branch }}" | ||
| VERSION="${VERSION#rel/}" | ||
| MAJOR_VERSION=$(echo "$VERSION" | cut -d '.' -f 1) | ||
| echo "CURRENT_VERSION=$VERSION" >> $GITHUB_OUTPUT | ||
| echo "MAJOR_VERSION=$MAJOR_VERSION" >> $GITHUB_OUTPUT | ||
|
|
||
| - name: "Generate GitHub App token" | ||
| id: app-token | ||
| uses: actions/create-github-app-token@v3 | ||
| with: | ||
| client-id: ${{ secrets.SAP_AI_SDK_BOT_CLIENT_ID }} | ||
| private-key: ${{ secrets.SAP_AI_SDK_BOT_PRIVATE_KEY }} | ||
| owner: SAP | ||
| repositories: ai-sdk | ||
| permission-contents: write | ||
| permission-pull-requests: write | ||
|
|
||
| - name: "Prepare Git" | ||
| run: | | ||
| git config --global user.email "cloudsdk@sap.com" | ||
| git config --global user.name "SAP Cloud SDK Bot" | ||
|
|
||
| - name: "Checkout Docs Repository" | ||
| uses: actions/checkout@v6 | ||
| with: | ||
| repository: ${{ env.DOCS_REPO }} | ||
| path: .ai-sdk-docs | ||
| token: ${{ steps.app-token.outputs.token }} | ||
|
|
||
| - name: "Create JavaDoc PR" | ||
| id: create-javadoc-pr | ||
| run: | | ||
| TARGET_DIR=.ai-sdk-docs/static/java-api/v${{ steps.determine-version.outputs.MAJOR_VERSION }} | ||
|
|
||
| rm -rf "$TARGET_DIR" | ||
| mkdir -p "$TARGET_DIR" | ||
| cp -R target/local-javadocs/aggregate/. "$TARGET_DIR" | ||
|
|
||
| cd .ai-sdk-docs | ||
| git add -A . | ||
|
|
||
| CHANGED_FILES="$(git status -s)" | ||
| if [[ -z "$CHANGED_FILES" ]]; then | ||
| echo "[DEBUG] No changes to API docs detected, skipping Pull Request creation." | ||
| exit 0 | ||
| fi | ||
|
n-o-u-r-h-a-n marked this conversation as resolved.
|
||
|
|
||
| echo "Committing new JavaDocs" | ||
| BRANCH_NAME=java/release-docs-${{ steps.determine-version.outputs.CURRENT_VERSION }} | ||
| git switch --create "$BRANCH_NAME" | ||
| git commit -m "chore: Update JavaDocs for release ${{ steps.determine-version.outputs.CURRENT_VERSION }}" | ||
| git push origin "$BRANCH_NAME" | ||
|
|
||
| echo "Creating PR" | ||
| PR_TITLE="Java: Update JavaDocs for release ${{ steps.determine-version.outputs.CURRENT_VERSION }}" | ||
| PR_BODY="Replace the contents of v${{ steps.determine-version.outputs.MAJOR_VERSION }} API docs with the latest release of the SDK." | ||
| PR_URL=$(gh pr create --title "$PR_TITLE" --body "$PR_BODY" --repo "${{ env.DOCS_REPO }}") | ||
| echo "PR: $PR_URL" >> $GITHUB_STEP_SUMMARY | ||
|
n-o-u-r-h-a-n marked this conversation as resolved.
|
||
| env: | ||
| GH_TOKEN: ${{ steps.app-token.outputs.token }} | ||
|
github-advanced-security[bot] marked this conversation as resolved.
Fixed
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.