feat(ci): add workflow for publishing JavaDoc to GitHub Pages

2026-05-12 15:42:39 +02:00
parent c514897ffc
commit 35293a0a57
3 changed files with 233 additions and 202 deletions
@@ -0,0 +1,141 @@
+name: Publish Docs
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Docs version to publish (e.g. 2.1.0)'
+        required: true
+        type: string
+
+  workflow_call:
+    inputs:
+      version:
+        description: 'Docs version to publish (e.g. 2.1.0)'
+        required: true
+        type: string
+    secrets:
+      MAVEN_USERNAME:
+        required: true
+      MAVEN_PASSWORD:
+        required: true
+
+jobs:
+  docs:
+    name: Build JavaDoc & Update gh-pages
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Temurin 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Build project (resolve deps + compile, skip tests)
+        run: mvn -B --settings .github/settings.xml clean verify -DskipTests
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      # javadoc:aggregate gira sulla root del progetto.
+      # L'output viene scritto in target/site/apidocs/ (root), NON in flash/target/...
+      - name: Generate aggregated JavaDoc
+        run: mvn -B --settings .github/settings.xml javadoc:aggregate -DskipTests
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Verify JavaDoc output exists
+        run: |
+          if [ ! -f "target/site/apidocs/index.html" ]; then
+            echo "ERROR: target/site/apidocs/index.html not found. JavaDoc generation failed."
+            exit 1
+          fi
+          echo "JavaDoc OK — $(find target/site/apidocs -name '*.html' | wc -l) HTML files generated."
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages-out
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Copy JavaDoc to versioned folder and latest
+        run: |
+          VERSION=${{ inputs.version }}
+          # Versioned snapshot
+          mkdir -p gh-pages-out/javadoc/$VERSION
+          cp -r target/site/apidocs/. gh-pages-out/javadoc/$VERSION/
+          # Always-current alias
+          rm -rf gh-pages-out/latest
+          mkdir -p gh-pages-out/latest
+          cp -r target/site/apidocs/. gh-pages-out/latest/
+
+      - name: Regenerate index.html
+        run: |
+          cd gh-pages-out
+          python3 - <<'EOF'
+          import os, re
+
+          def version_key(v):
+              parts = re.findall(r'\d+', v)
+              return [int(p) for p in parts] if parts else [0]
+
+          versions = sorted(
+              [d for d in os.listdir("javadoc") if os.path.isdir(f"javadoc/{d}")],
+              key=version_key,
+              reverse=True
+          )
+
+          rows = "\n".join(
+              f'      <li><a href="javadoc/{v}/index.html">{v}</a></li>'
+              for v in versions
+          )
+
+          html = f"""<!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Flash JavaDoc</title>
+            <style>
+              body {{ font-family: Inter, Arial, sans-serif; max-width: 720px; margin: 5rem auto; padding: 0 1.5rem; color: #1f2937; background: #fff; }}
+              h1 {{ font-size: 2rem; margin-bottom: 0.5rem; letter-spacing: -0.02em; }}
+              p {{ color: #6b7280; line-height: 1.6; }}
+              ul {{ list-style: none; padding: 0; margin: 2rem 0 0; border-top: 1px solid #e5e7eb; }}
+              li {{ border-bottom: 1px solid #e5e7eb; }}
+              a {{ display: block; padding: 1rem 0; color: #111827; text-decoration: none; font-weight: 600; }}
+              a:hover {{ text-decoration: underline; }}
+            </style>
+          </head>
+          <body>
+            <h1>Flash — JavaDoc</h1>
+            <p>Browse the published API documentation for each release.</p>
+            <ul>
+          {rows}
+            </ul>
+          </body>
+          </html>"""
+
+          with open("index.html", "w", encoding="utf-8") as f:
+              f.write(html)
+          print(f"index.html generated — {len(versions)} version(s): {versions}")
+          EOF
+
+      - name: Push gh-pages
+        run: |
+          cd gh-pages-out
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet || git commit -m "docs(javadoc): publish ${{ inputs.version }}"
+          git push origin gh-pages