roxygen.yaml

---
name: Roxygen 🅾

on:
  push:
    branches:
      - main
      - pre-release
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
    branches:
      - main
      - pre-release
  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
    secrets:
      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_4.2.1_bioc_3.15:latest

    steps:
      - name: Get branch names 🌿
        id: branch-name
        uses: tj-actions/branch-names@v5

      - name: Checkout repo 🛎
        uses: actions/checkout@v3
        with:
          ref: ${{ steps.branch-name.outputs.head_ref_branch }}
          path: ${{ github.event.repository.name }}
          fetch-depth: 0

      - name: Run Staged dependencies 🎦
        uses: insightsengineering/staged-dependencies-action@v1
        with:
          run-system-dependencies: ${{ inputs.install-system-dependencies }}
        env:
          GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
          SD_REPO_PATH: ${{ github.event.repository.name }}
          SD_ENABLE_CHECK: ${{ inputs.enable-staged-dependencies-check }}

      - name: Generate man pages 📄
        run: |
          setwd("${{ github.event.repository.name }}")
          logfile <- "roxygen_${{ github.event.repository.name }}.log"
          con <- file(logfile)
          sink(con, append = TRUE, split = TRUE)
          sink(con, append = TRUE, type = "message")
          roxygen2::roxygenize('.', roclets = c('rd', 'collate', 'namespace'))
          sink()
          sink(type = "message")
          logs <- readLines(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}

      - name: Roxygen check 🅾
        run: |
          cd ${{ github.event.repository.name }}
          git status -s
          if [[ -n `git status -s | grep man` ]]
          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/*
            if [ "${{ inputs.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 add man/*
              git commit -m "[skip actions] ROxygen Man Pages Auto Update"
              git pull origin ${GITHUB_HEAD_REF}
              git push -v origin ${GITHUB_HEAD_REF}
            }
            else {
              echo -e "\n💻 Please rerun the following command on your workstation and push your changes"
              echo "--------------------------------------------------------------------"
              echo "roxygen2::roxygenize('.', roclets = c('rd', 'collate', 'namespace'))"
              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"
            }
            fi
            exit 1
          } else {
            echo "💚 Manuals are up-to-date with roxygen comments"
          }
          fi
        shell: bash