Deploy Versioned Javadoc (Manual Trigger) #156
Workflow file for this run
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
| name: JavaDoc Releases | |
| on: | |
| push: | |
| tags: | |
| - "*" # Only publish docs for tags | |
| delete: | |
| tags: | |
| - "*" # Auto-remove docs when tags are deleted | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| pages: write | |
| id-token: write | |
| jobs: | |
| build: | |
| name: Build JavaDoc | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout source | |
| uses: actions/checkout@v5 | |
| - name: Set up JDK | |
| uses: actions/setup-java@v5 | |
| with: | |
| distribution: temurin | |
| java-version: 25 | |
| - name: Set up Maven cache | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| ~/.m2/repository | |
| key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml') }} | |
| restore-keys: | | |
| maven-${{ runner.os }}- | |
| - name: Build JavaDoc | |
| run: mvn -B javadoc:javadoc | |
| # Upload for GitHub Pages preview (this is optional) | |
| - name: Upload Pages Artifact | |
| uses: actions/upload-pages-artifact@v4 | |
| with: | |
| path: target/site/apidocs | |
| update-gh-pages: | |
| name: Update gh-pages | |
| needs: build | |
| runs-on: ubuntu-latest | |
| if: github.event_name != 'delete' # skip this job on delete events | |
| steps: | |
| - name: Checkout gh-pages branch | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: gh-pages | |
| path: gh-pages | |
| - name: Copy Javadoc into versioned folder | |
| run: | | |
| TAG="${GITHUB_REF_NAME}" | |
| VERSION_DIR="docs/${TAG}" | |
| rm -rf "gh-pages/${VERSION_DIR}" | |
| mkdir -p "gh-pages/${VERSION_DIR}" | |
| cp -r target/site/apidocs/* "gh-pages/${VERSION_DIR}/" | |
| - name: Regenerate multi-version index.html | |
| run: | | |
| cd gh-pages | |
| # Create index header | |
| cat > index.html << 'EOF' | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="UTF-8"/> | |
| <title>Javadoc Versions</title> | |
| <style> | |
| body { font-family: Arial; padding: 2rem; max-width: 800px; margin: auto; } | |
| h1 { font-size: 2rem; } | |
| ul { line-height: 1.8; font-size: 1.1rem; } | |
| </style> | |
| </head> | |
| <body> | |
| <h1>Available Javadoc Versions</h1> | |
| <ul> | |
| EOF | |
| # Insert entries for each version directory | |
| for dir in docs/*; do | |
| [ -d "$dir" ] || continue | |
| ver=$(basename "$dir") | |
| echo "<li><a href=\"docs/$ver/\">$ver</a></li>" >> index.html | |
| done | |
| # Close HTML | |
| cat >> index.html << 'EOF' | |
| </ul> | |
| </body> | |
| </html> | |
| EOF | |
| - name: Commit & push changes | |
| run: | | |
| cd gh-pages | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git config user.name "github-actions[bot]" | |
| if git diff --quiet; then | |
| echo "No changes to commit" | |
| exit 0 | |
| fi | |
| git add . | |
| git commit -m "Update release Javadoc for ${GITHUB_REF_NAME}" | |
| git push origin gh-pages | |
| delete-tag-docs: | |
| name: Remove deleted tag docs | |
| runs-on: ubuntu-latest | |
| if: github.event_name == 'delete' && github.event.ref_type == 'tag' | |
| steps: | |
| - name: Checkout gh-pages | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: gh-pages | |
| path: gh-pages | |
| - name: Remove documentation for deleted tag | |
| run: | | |
| TAG="${GITHUB_REF_NAME}" | |
| VERSION_DIR="docs/${TAG}" | |
| rm -rf "gh-pages/${VERSION_DIR}" | |
| - name: Rebuild index.html | |
| run: | | |
| cd gh-pages | |
| # Regenerate index.html (same as above) | |
| cat > index.html << 'EOF' | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="UTF-8"/> | |
| <title>Javadoc Versions</title> | |
| <style> | |
| body { font-family: Arial; padding: 2rem; max-width: 800px; margin: auto; } | |
| h1 { font-size: 2rem; } | |
| ul { line-height: 1.8; font-size: 1.1rem; } | |
| </style> | |
| </head> | |
| <body> | |
| <h1>Available Javadoc Versions</h1> | |
| <ul> | |
| EOF | |
| for dir in docs/*; do | |
| [ -d "$dir" ] || continue | |
| ver=$(basename "$dir") | |
| echo "<li><a href=\"docs/$ver/\">$ver</a></li>" >> index.html | |
| done | |
| cat >> index.html << 'EOF' | |
| </ul> | |
| </body> | |
| </html> | |
| EOF | |
| - name: Commit & push removal | |
| run: | | |
| cd gh-pages | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git config user.name "github-actions[bot]" | |
| if git diff --quiet; then | |
| echo "No changes to commit" | |
| exit 0 | |
| fi | |
| git add . | |
| git commit -m "Remove Javadoc for deleted tag ${GITHUB_REF_NAME}" | |
| git push origin gh-pages | |
| # Summary of Features | |
| # Multi-version docs (docs/<tag>/) | |
| # Auto-generated index.html | |
| # Only publish for tags | |
| # Delete docs when tags are deleted | |
| # Upload Pages artifact | |
| # Maven dependency caching | |
| # No third-party actions | |
| # No force-push | |
| # Clean HTML layout |