Roxygen.yaml

---
    name: Roxygen 🅾
    
    on:
      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: "."
        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/checkout@v4
            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/checkout@v4
            if: github.event_name != 'pull_request'
            # with:
            #   ref: ${{ steps.branch-name.outputs.head_ref_branch }}
            #   path: ${{ github.event.repository.name }}

          - name: Setup R
            uses: r-lib/actions/setup-r@v2
            with:
              use-public-rspm: true
      
          - name: Setup R dependencies
            uses: r-lib/actions/setup-r-dependencies@v2
            with:
              extra-packages: any::roxygen2
    
        #   - name: Restore SD cache 💰
        #     uses: actions/cache@v4
        #     with:
        #       key: sd-${{ runner.os }}-${{ github.event.repository.name }}
        #       path: ~/.staged.dependencies
    
        #   - name: Run Staged dependencies 🎦
        #     uses: insightsengineering/staged-dependencies-action@v1
        #     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: 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 }}
    
          - 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 }}