diff --git a/.github/workflows/publish-javadoc.yml b/.github/workflows/publish-javadoc.yml new file mode 100644 index 000000000..dce118529 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 27d31edf9..47b779e31 100644 --- a/README.md +++ b/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 `, where `` 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 " --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. \ No newline at end of file +public automatically.