Create a workflow to publish the Javadoc when a specific issue is cre…

…ated

.github/workflows/publish-javadoc.yml

@@ -0,0 +1,103 @@
+name: Publish javadoc
+
+on:
+  issues:
+    types: [ opened ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish-javadoc:
+    name: Publish javadoc
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Extract Robolectric version
+        id: robolectric_version
+        run: |
+          authorAssociation=${{ github.event.issue.author_association }}
+
+          if [[ "$authorAssociation" == "COLLABORATOR" || "$authorAssociation" == "MEMBER" || "$authorAssociation" == "OWNER" ]]; then
+            issueTitle=${{ github.event.issue.title }}
+
+            if [[ "$issueTitle" =~ ^Publish\ javadoc\ for\ (([0-9]+\.[0-9]+)(\.[0-9]+)?)$ ]]; then
+              robolectricMinorVersion=${BASH_REMATCH[2]}
+              robolectricPatchVersion=${BASH_REMATCH[1]}
+
+              echo "minorVersion=$robolectricMinorVersion" > $GITHUB_OUTPUT
+              echo "patchVersion=$robolectricPatchVersion" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+      - name: Checkout Robolectric
+        uses: actions/checkout@v4
+        if: ${{ steps.robolectric_version.outputs.patchVersion }}
+        with:
+          repository: robolectric/robolectric
+          path: robolectric
+          ref: robolectric-${{ steps.robolectric_version.outputs.patchVersion }}
+
+      - name: Checkout robolectric.github.io
+        uses: actions/checkout@v4
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        with:
+          path: robolectric.github.io
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        with:
+          distribution: 'adopt'
+          java-version: 17
+
+      - name: Assemble and aggregate javadoc
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        run: |
+          cd robolectric
+          ./gradlew clean aggregateDocs
+
+      - name: Move the new javadoc
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        run: |
+          cd robolectric.github.io
+          targetFolder=docs/javadoc/${{ steps.robolectric_version.outputs.minorVersion }}
+          if [ -e $targetFolder ]; then
+            rm -r $targetFolder
+          fi
+
+          mv ../robolectric/build/docs/javadoc $targetFolder
+
+      - name: Update Robolectric version in mkdocs.yml
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        run: |
+          cd robolectric.github.io
+          sed -i 's/^      current: ".*"$/      current: "${{ steps.robolectric_version.outputs.minorVersion }}"/' mkdocs.yml
+          sed -i 's/^      current_patched: ".*"$/      current_patched: "${{ steps.robolectric_version.outputs.patchVersion }}"/' mkdocs.yml
+
+          if [ "${{ steps.robolectric_version.outputs.minorVersion }}" == "${{ steps.robolectric_version.outputs.patchVersion }}" ]; then
+            sed -i 's/^\(    - "Javadoc":\)$/\1\n      - "${{ steps.robolectric_version.outputs.minorVersion }}": \/javadoc\/${{ steps.robolectric_version.outputs.minorVersion }}\//' mkdocs.yml
+          fi
+
+      - name: Update latest javadoc symbolic link
+        if: ${{ steps.robolectric_version.outputs.minorVersion }}
+        run: |
+          cd robolectric.github.io
+          ln -sfn ${{ steps.robolectric_version.outputs.minorVersion }} docs/javadoc/latest
+
+      - name: Create Pull Request
+        if: ${{ steps.robolectric_version.outputs.patchVersion }}
+        run: |
+          cd robolectric.github.io
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b publish-javadoc-robolectric-${{ steps.robolectric_version.outputs.patchVersion }}
+          git add -A
+          git commit -m "Publish javadoc for Robolectric ${{ steps.robolectric_version.outputs.patchVersion }}" \
+            -m "- Add javadoc for Robolectric ${{ steps.robolectric_version.outputs.patchVersion }}." \
+            -m "- Update mkdocs.yml to add a navigation entry to the new javadoc." \
+            -m "- Update mkdocs.yml to use version ${{ steps.robolectric_version.outputs.patchVersion }}."
+            -m "Fixes #${{ github.event.issue.id }}"
+          git push --set-upstream origin publish-javadoc-robolectric-${{ steps.robolectric_version.outputs.patchVersion }}
+          gh pr create --fill

README.md

@@ -24,11 +24,30 @@ Once your Pull Request is merged, the documentation will be automatically built
 
 ## Javadocs
 
-When a new version of Robolectric is released, the `javadoc` directory needs to be updated. We can get the last steps to generate the Javadocs in [Robolectric Wiki's release part](https://github.com/robolectric/robolectric/wiki/Performing-a-Release#release).
+When a new version of Robolectric is released, the [`docs/javadoc`](docs/javadoc) directory needs to be updated. This can be achieved either automatically, or manually.
+
+### Automatic publication
+
+The simplest way to publish the javadoc for a specific version is to [create an issue](https://github.com/robolectric/robolectric.github.io/issues/new) whose title is `Publish javadoc for <version>`, where `<version>` is Robolectric's new version (for example `4.12`).
+
+> [!NOTE]
+> If you provide a bugfix version, it will overwrite the corresponding minor version's javadoc.
+> For example, passing version `4.12.2` will update the javadoc for Robolectric 4.12.
+
+This will trigger the [`publish-javadoc.yml` workflow](.github/workflows/publish-javadoc.yml) to build and publish the corresponding javadoc.
+
+> [!TIP]
+> If you use the [`gh`](https://cli.github.com/) command line tool, you can use the following command:
+> 
+> `gh issue create --title "Publish javadoc for <version>" --body ""`
+
+### Manual publication
+
+To manually publish the javadoc, you can follow the guide in [Robolectric Wiki's release part](https://github.com/robolectric/robolectric/wiki/Performing-a-Release#update-docs).
 
 ## Deploy process
 
 When a new PR is merged, GitHub Actions will build and push site code
 to `gh-pages` branch. The repository has configured to deploy the site
 with `gh-phages` branch, and then GitHub Pages will deploy the site
-public automatically.
+public automatically.