ci: attach the generated Javadoc to each release as a tar.gz

.github/workflows/ci.yml

@@ -37,6 +37,16 @@ jobs:
             --title "$GITHUB_REF_NAME" \
             --notes-file /tmp/release-notes.md
 
+  # Attaches the generated documentation to the release, for the QTSurfer website to publish.
+  reference-docs:
+    needs: release
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+    uses: ./.github/workflows/reference-docs.yml
+    with:
+      tag: ${{ github.ref_name }}
+
   docs:
     needs: build
     runs-on: ubuntu-latest

.github/workflows/reference-docs.yml

@@ -0,0 +1,53 @@
+name: Reference documentation archive
+
+# Attaches the generated Javadoc of a release to that release, as a tar.gz with its checksum, so the
+# QTSurfer website can publish it. It runs after every release (see ci.yml) and by hand to build the
+# archive of a release that already exists.
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Release tag to document
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to document
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    env:
+      TAG: ${{ inputs.tag }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: Check that the release exists
+        run: gh release view "$TAG" --repo "$GITHUB_REPOSITORY" > /dev/null
+      - uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: 'maven'
+      # These sources are generated from the spec, so they have to exist before
+      # javadoc can read them.
+      - name: Generate javadoc
+        run: mvn -B generate-sources javadoc:javadoc
+      - name: Package the documentation
+        run: |
+          name="api-client-java-docs-${TAG}"
+          tar -czf "${name}.tar.gz" -C target/site/apidocs .
+          sha256sum "${name}.tar.gz" > "${name}.tar.gz.sha256"
+      - name: Attach it to the release
+        run: |
+          name="api-client-java-docs-${TAG}"
+          gh release upload "$TAG" "${name}.tar.gz" "${name}.tar.gz.sha256" \
+            --repo "$GITHUB_REPOSITORY" --clobber