.github/workflows/document.yaml

# Rebuilds the documentation and fails on links roxygen2 cannot resolve.
#
# Those arise from linking to a function marked @noRd, which has no topic to
# link to. They never reach a manual page, so R CMD check says nothing and a
# comparison of the generated files finds nothing either - the only trace is a
# message while documenting, which is easy to miss.
on:
  push:
    branches: [main, master]
    paths:
      - 'R/**'
      - 'man/**'
      - 'NAMESPACE'
      - 'DESCRIPTION'
      - '.github/workflows/document.yaml'
  pull_request:
    branches: [main, master]

name: document

jobs:
  document:
    runs-on: ubuntu-latest

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - uses: actions/checkout@v3

      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::roxygen2

      - name: Document, and refuse links that do not resolve
        shell: Rscript {0}
        run: |
          messages <- character()
          withCallingHandlers(
            roxygen2::roxygenise(),
            message = function(m) {
              messages <<- c(messages, conditionMessage(m))
              invokeRestart("muffleMessage")
            }
          )
          cat(messages, sep = "")

          # reported as a message rather than a warning, so it has to be looked for
          unresolved <- grep("Could not resolve link", messages, value = TRUE)
          if (length(unresolved) > 0) {
            stop(
              sprintf(
                "roxygen2 could not resolve %d link%s. A function marked @noRd has no topic to link to; write it as `code` instead.",
                length(unresolved),
                if (length(unresolved) == 1) "" else "s"
              ),
              call. = FALSE
            )
          }