pkgdown.yml

on:
  workflow_dispatch:
    inputs:
      r-version:
        description: "The version of R to use"
        default: "release"
        required: false
        type: choice
        options:
          - devel
          - latest
      skip-multiversion-docs:
        description: "Skip creation of multi-version docs"
        default: false
        required: false
        type: boolean
      multiversion-docs-landing-page:
        description: "Ref to use for the multiversion docs landing page"
        default: main
        required: false
        type: string
      latest-tag-alt-name:
        description: "An alternate name to use for 'latest-tag' for multiversion pkgdown docs"
        default: ""
        required: false
        type: string
      branches-or-tags-to-list:
        description: |
          Which branches or tags should be listed under the
          'Versions' dropdown menu on the landing page?
          This input should be a regular expression in R.
        required: false
        default: >-
          ^main$|^devel$|^pre-release$|^latest-tag$|^cran-release$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$
        type: string
  workflow_call:
    inputs:
      r-version:
        description: "The version of R to use"
        default: "release"
        required: false
        type: string
      skip-multiversion-docs:
        description: "Skip creation of multi-version docs"
        default: false
        required: false
        type: boolean
      insert-tweak-page-hook:
        description: "This option customizes the pkgdown::tweak_page function by adding a new custom hook to fix rdrr.io links"
        default: true
        required: false
        type: boolean
      multiversion-docs-landing-page:
        description: "Ref to use for the multiversion docs landing page"
        default: main
        required: false
        type: string
      latest-tag-alt-name:
        description: "An alternate name to use for 'latest-tag' for multiversion pkgdown docs"
        default: ""
        required: false
        type: string
      branches-or-tags-to-list:
        description: |
          Which branches or tags should be listed under the
          'Versions' dropdown menu on the landing page?
          This input should be a regular expression in R.
        required: false
        default: >-
          ^main$|^devel$|^pre-release$|^latest-tag$|^cran-release$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$
        type: string
    secrets:
      GITHUB_PAT:
        required: false
        description: GitHub API access token, which might be needed for downstream ops or rendering.

name: Documentation

concurrency:
  group: pkgdown-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  pkgdown:
    name: pkgdown
    runs-on: ubuntu-latest
    container:
      image: "ghcr.io/pharmaverse/admiralci-${{ inputs.r-version }}:latest"
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    if: >
      !contains(github.event.commits[0].message, '[skip docs]')
    steps:
      ##################### BEGIN boilerplate steps #####################
      - name: Get branch names
        id: branch-name
        uses: tj-actions/branch-names@v8

      - name: Checkout repo (PR) 🛎
        uses: actions/checkout@v4.2.2
        if: github.event_name == 'pull_request'
        with:
          ref: ${{ steps.branch-name.outputs.head_ref_branch }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}

      - name: Checkout repository
        uses: actions/checkout@v4.2.2
        if: github.event_name != 'pull_request'
        with:
          ref: ${{ steps.branch-name.outputs.head_ref_branch }}
          # https://github.com/actions/runner/issues/2033

      - name: Set-up safe dir
        run: |
          echo "${PWD}"
          git config --global --add safe.directory "${GITHUB_WORKSPACE}"
        shell: bash

      - name: Normalize inputs
        id: normalizer
        run: |
          function normalize() {
            local var=$1
            if [ "$var" == "" ]
            then {
              var=$2
            }
            fi
            echo ${var}
          }
          DOCS_LANDING_PAGE=$(normalize ${{ inputs.multiversion-docs-landing-page }} main)
          echo "DOCS_LANDING_PAGE=$DOCS_LANDING_PAGE" >> $GITHUB_OUTPUT
        shell: bash

      - name: Restore cache
        uses: actions/cache@v4
        with:
          path: |
            ~/.staged.dependencies
          key: staged-deps

      - name: Setup pandoc
        uses: r-lib/actions/setup-pandoc@v2

      - name: Run Staged dependencies
        uses: insightsengineering/staged-dependencies-action@v1
        with:
          run-system-dependencies: false
          renv-restore: false
          enable-check: false
          direction: upstream
          git-ref: ${{ steps.branch-name.outputs.current_branch }}
        env:
          GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

      - name: Install dependencies from DESCRIPTION
        run: |
          remotes::install_local(force = TRUE, dependencies = TRUE)
        shell: Rscript {0}

      ##################### END boilerplate steps #####################

      - name: Install package
        run: renv::install(".", dependencies = "no-deps")
        shell: Rscript {0}

      - name: Add script to fix rdrr.io links for pharmaverse packages
        uses: "DamianReeves/write-file-action@v1.2"
        if: inputs.insert-tweak-page-hook
        with:
          path: ./.Rprofile
          write-mode: append
          contents: |
            tweak_rdrr_url <- function(...) {
              html <- ..1

              links <- xml2::xml_find_all(html, ".//a")
              if (length(links) == 0) {
                return(invisible())
              }

              hrefs <- xml2::xml_attr(links, "href")
              needs_tweak <- grepl("^https://rdrr.io/pkg/", hrefs) & xml2::url_parse(hrefs)$scheme == "https"

              fix_links <- function(x) {
                pattern <- "/pkg/(\\w+)/man/(\\w+)\\.html"

                matches <- stringr::str_match(x, pattern)
                package_name <- matches[2]
                function_name <- matches[3]

                if (!(grepl("^admiral", package_name) || package_name %in% c("matatools", "matacore"))) {
                    return(x)
                }

                sprintf("https://pharmaverse.github.io/%s/main/reference/%s.html", package_name, function_name)
              }

              if (any(needs_tweak)) {
                purrr::walk2(
                  links[needs_tweak],
                  purrr::map(hrefs[needs_tweak], fix_links),
                  xml2::xml_set_attr,
                  attr = "href"
                )
              }

              invisible()
            }

            if ("${{ inputs.insert-tweak-page-hook }}" == "true") {
              setHook("UserHook::admiralci::tweak_page", tweak_rdrr_url)
              print("Tweak rdrr.io links for admiral pharmaverse packages.")
            }

      - name: Publish documentation
        run: |
          git config --local user.email "actions@github.com"
          git config --local user.name "GitHub Actions"
          SUBDIR_OPTION=""
          if [ "${{ inputs.skip-multiversion-docs }}" != "true" ]
          then {
            SUBDIR_OPTION="subdir = \"${GITHUB_REF##*/}\","
          }
          fi
          Rscript - <<EOF
          if ("${{ inputs.insert-tweak-page-hook }}" == "true") {
            pkgdown_env <- asNamespace("pkgdown")
            rlang::env_unlock(env = pkgdown_env)
            rlang::env_binding_unlock(env = pkgdown_env)
            pkgdown_env\$call_hook <- function(hook_name, ...) {
              hooks <- getHook(paste0("UserHook::admiralci::", hook_name))
              if (!is.list(hooks)) {
                hooks <- list(hooks)
              }
              purrr::map(hooks, function(fun) {
                fun(...)
              }) |>
                invisible()
            }
            environment(pkgdown_env\$call_hook) <- pkgdown_env
            tweak_page <- body(pkgdown_env\$tweak_page)
            body(pkgdown_env\$tweak_page) <-
              as.call(
                append(
                  as.list(tweak_page),
                  expression(call_hook("tweak_page", html, name, pkg)),
                  after=length(tweak_page)
                )
              )
            rlang::env_binding_lock(env = pkgdown_env)
            rlang::env_lock(pkgdown_env)
            require(desc::desc_get("Package"), character.only = TRUE)
          }
          clean = FALSE
          if ("${{ inputs.skip-multiversion-docs }}" == "true"){
            clean = TRUE
          }
          pkgdown::deploy_to_branch(
            new_process = FALSE,
            ${SUBDIR_OPTION}
            clean = clean
          )
          EOF
        env:
          GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

  multi-version-docs:
    name: Multi-version docs
    needs: pkgdown
    runs-on: ubuntu-latest
    if: >
      !inputs.skip-multiversion-docs &&
        !contains(github.event.commits[0].message, '[skip docs]')
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4.2.2
        with:
          path: ${{ github.event.repository.name }}
          ref: "gh-pages"

      - name: Normalize inputs
        id: normalizer
        run: |
          function normalize() {
            local var=$1
            if [ "$var" == "" ]
            then {
              var=$2
            }
            fi
            echo ${var}
          }
          DOCS_LANDING_PAGE=$(normalize ${{ inputs.multiversion-docs-landing-page }} main)
          echo "DOCS_LANDING_PAGE=$DOCS_LANDING_PAGE" >> $GITHUB_OUTPUT
          echo "Waiting for 45 seconds for pages build and deployment jobs finish"
          echo "This is to avoid concurrency-related cancellations imposed by the step below."
          sleep 45
        shell: bash

      - name: Create and publish docs
        uses: insightsengineering/r-pkgdown-multiversion@v3
        with:
          path: ${{ github.event.repository.name }}
          default-landing-page: "${{ steps.normalizer.outputs.DOCS_LANDING_PAGE }}"
          latest-tag-alt-name: "${{ inputs.latest-tag-alt-name }}"
          branches-or-tags-to-list: ${{ inputs.branches-or-tags-to-list }}