feat: Upgrade the multiversion docs action (#259) #1339
This file contains 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: Roxygen 🅾 | |
| on: | |
| push: | |
| branches: | |
| - main | |
| pull_request: | |
| types: | |
| - opened | |
| - synchronize | |
| - reopened | |
| - ready_for_review | |
| branches: | |
| - main | |
| workflow_dispatch: | |
| workflow_call: | |
| inputs: | |
| install-system-dependencies: | |
| description: Check for and install system dependencies | |
| required: false | |
| default: false | |
| type: boolean | |
| enable-staged-dependencies-check: | |
| description: Enable staged dependencies YAML check | |
| required: false | |
| default: false | |
| type: boolean | |
| auto-update: | |
| description: If man pages are not up-to-date, they will be automatically updated and committed back to the branch. | |
| required: false | |
| default: false | |
| type: boolean | |
| sd-direction: | |
| description: The direction to use to install staged dependencies. Choose between 'upstream', 'downstream' and 'all' | |
| required: false | |
| type: string | |
| default: upstream | |
| package-subdirectory: | |
| description: Subdirectory in the repository, where the R package is located. | |
| required: false | |
| type: string | |
| default: "." | |
| deps-installation-method: | |
| description: | | |
| Which method for installing R package dependencies to use? Supported values are: | |
| staged-dependencies | |
| setup-r-dependencies | |
| required: false | |
| type: string | |
| default: staged-dependencies | |
| lookup-refs: | |
| description: | | |
| Passed to insightsengineering/setup-r-dependencies. See its documentation. | |
| Used only if deps-installation-method == 'setup-r-dependencies'. | |
| required: false | |
| type: string | |
| default: "" | |
| secrets: | |
| REPO_GITHUB_TOKEN: | |
| description: | | |
| Github token with read access to repositories, required for staged.dependencies installation | |
| required: false | |
| concurrency: | |
| group: roxygen-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| roxygen: | |
| name: Manual pages check 🏁 | |
| runs-on: ubuntu-latest | |
| if: > | |
| !contains(github.event.commits[0].message, '[skip roxygen]') | |
| && github.event.pull_request.draft == false | |
| container: | |
| image: ghcr.io/insightsengineering/rstudio:latest | |
| steps: | |
| - name: Setup token 🔑 | |
| id: github-token | |
| run: | | |
| if [ "${{ secrets.REPO_GITHUB_TOKEN }}" == "" ]; then | |
| echo "REPO_GITHUB_TOKEN is empty. Substituting it with GITHUB_TOKEN." | |
| echo "token=${{ secrets.GITHUB_TOKEN }}" >> $GITHUB_OUTPUT | |
| else | |
| echo "Using REPO_GITHUB_TOKEN." | |
| echo "token=${{ secrets.REPO_GITHUB_TOKEN }}" >> $GITHUB_OUTPUT | |
| fi | |
| shell: bash | |
| - name: Get branch names 🌿 | |
| id: branch-name | |
| uses: tj-actions/branch-names@v7 | |
| - name: Checkout repo (PR) 🛎 | |
| uses: actions/[email protected] | |
| if: github.event_name == 'pull_request' | |
| with: | |
| ref: ${{ steps.branch-name.outputs.head_ref_branch }} | |
| path: ${{ github.event.repository.name }} | |
| repository: ${{ github.event.pull_request.head.repo.full_name }} | |
| token: ${{ steps.github-token.outputs.token }} | |
| - name: Checkout repo 🛎 | |
| uses: actions/[email protected] | |
| if: github.event_name != 'pull_request' | |
| with: | |
| ref: ${{ steps.branch-name.outputs.head_ref_branch }} | |
| path: ${{ github.event.repository.name }} | |
| - name: Check commit message 💬 | |
| run: | | |
| git config --global --add safe.directory $(pwd) | |
| export head_commit_message="$(git show -s --format=%B | tr '\r\n' ' ' | tr '\n' ' ')" | |
| echo "head_commit_message = $head_commit_message" | |
| if [[ $head_commit_message == *"$SKIP_INSTRUCTION"* ]]; then | |
| echo "Skip instruction detected - cancelling the workflow." | |
| exit 1 | |
| fi | |
| shell: bash | |
| working-directory: ${{ github.event.repository.name }} | |
| env: | |
| SKIP_INSTRUCTION: "[skip roxygen]" | |
| - name: Normalize variables 📏 | |
| run: | | |
| deps_installation_method="${{ inputs.deps-installation-method }}" | |
| echo "deps_installation_method=${deps_installation_method:-staged-dependencies}" >> $GITHUB_ENV | |
| shell: bash | |
| - name: Restore SD cache 💰 | |
| if: >- | |
| env.deps_installation_method == 'staged-dependencies' | |
| uses: actions/cache@v4 | |
| with: | |
| key: sd-${{ runner.os }}-${{ github.event.repository.name }} | |
| path: ~/.staged.dependencies | |
| - name: Run Staged dependencies 🎦 | |
| if: >- | |
| env.deps_installation_method == 'staged-dependencies' | |
| uses: insightsengineering/staged-dependencies-action@v2 | |
| env: | |
| GITHUB_PAT: ${{ steps.github-token.outputs.token }} | |
| with: | |
| path: ${{ github.event.repository.name }}/${{ inputs.package-subdirectory }} | |
| enable-check: ${{ inputs.enable-staged-dependencies-check }} | |
| run-system-dependencies: ${{ inputs.install-system-dependencies }} | |
| direction: ${{ inputs.sd-direction }} | |
| - name: Setup R dependencies 🎦 | |
| if: >- | |
| env.deps_installation_method == 'setup-r-dependencies' | |
| uses: insightsengineering/setup-r-dependencies@v1 | |
| with: | |
| lookup-refs: ${{ inputs.lookup-refs }} | |
| github-token: ${{ steps.github-token.outputs.token }} | |
| repository-path: ${{ github.event.repository.name }} | |
| - name: Generate man pages 📄 | |
| run: | | |
| logfile <- "roxygen_${{ github.event.repository.name }}.log" | |
| con <- file(logfile) | |
| sink(con, append = TRUE, split = TRUE) | |
| sink(con, append = TRUE, type = "message") | |
| roxygen2::roxygenize('.') | |
| sink() | |
| sink(type = "message") | |
| logs <- readLines(logfile) | |
| cat("🪵 Log output of 'roxygen2::roxygenize()':\n") | |
| system2("cat", logfile) | |
| error_marker <- grep("Error:", logs) | |
| warnings_marker <- grep("Warning message", logs) | |
| if (length(warnings_marker) > 0) { | |
| cat("⚠ One or more warnings were generated during the roxygen build:\n") | |
| cat(logs[warnings_marker[[1]]:length(logs)], sep = "\n") | |
| stop("Please 🙏 fix the warnings shown below this message 👇") | |
| } | |
| if (length(error_marker) > 0) { | |
| cat("☠ One or more errors were generated during the roxygen build:\n") | |
| cat(logs[error_marker[[1]]:length(logs)], sep = "\n") | |
| stop("Please 🙏 fix the errors shown below this message 👇") | |
| } | |
| shell: Rscript {0} | |
| working-directory: ${{ github.event.repository.name }}/${{ inputs.package-subdirectory }} | |
| env: | |
| LANG: en_US.UTF-8 | |
| - name: Roxygen check 🅾 | |
| run: | | |
| AUTO_UPDATE=${{ inputs.auto-update }} | |
| if [[ -n `git status -s | grep -E "man|DESCRIPTION"` ]] | |
| then { | |
| ROXYGEN_VERSION="$(Rscript -e 'packageVersion("roxygen2")' | awk '{print $NF}')" | |
| echo "🙈 Manuals are not up-to-date with roxygen comments!" | |
| echo "🔀 The following differences were noted:" | |
| git diff man/* DESCRIPTION | |
| # Attempt to commit and push man-page updates | |
| if [ "${AUTO_UPDATE}" == "true" ] | |
| then { | |
| echo "Regenerating man pages via auto-update" | |
| git config --global user.name "github-actions" | |
| git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" | |
| git config pull.rebase false | |
| BRANCH_NAME="${{ steps.branch-name.outputs.head_ref_branch }}" | |
| git pull origin ${BRANCH_NAME} || true | |
| git add -A man/ DESCRIPTION | |
| git commit -m "[skip roxygen] [skip vbump] Roxygen Man Pages Auto Update" | |
| git push -v origin HEAD:${BRANCH_NAME} || \ | |
| (echo "⚠️ Could not push to ${BRANCH_NAME} on $(git remote -v show -n origin | grep Push)" && \ | |
| AUTO_UPDATE=failed) | |
| } | |
| fi | |
| # If auto-update is disabled or is unsuccessful, let 'em know to fix manually | |
| if [ "${AUTO_UPDATE}" != "true" ] | |
| then { | |
| echo -e "\n💻 Please rerun the following command on your workstation and push your changes" | |
| echo "--------------------------------------------------------------------" | |
| echo "roxygen2::roxygenize('.')" | |
| echo "--------------------------------------------------------------------" | |
| echo "ℹ roxygen2 version that was used in this workflow: $ROXYGEN_VERSION" | |
| echo "🙏 Please ensure that the 'RoxygenNote' field in the DESCRIPTION file matches this version" | |
| exit 1 | |
| } | |
| fi | |
| } else { | |
| echo "💚 Manuals are up-to-date with roxygen comments" | |
| } | |
| fi | |
| shell: bash | |
| working-directory: ${{ github.event.repository.name }}/${{ inputs.package-subdirectory }} |