pkgdown.yaml

---
name: Pkgdown Docs 📚

on:
  push:
    tags:
      - "v*"
    branches:
      - main
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
    branches:
      - main
    paths:
      - inst/templates/**
      - _pkgdown.yaml
      - DESCRIPTION
      - "**.md"
      - "**.Rmd"
      - man/**
      - LICENSE.*
      - NAMESPACE
  workflow_dispatch:
  workflow_call:
    secrets:
      REPO_GITHUB_TOKEN:
        description: |
          Github token with read access to repositories, required for staged.dependencies installation
        required: false
    inputs:
      install-system-dependencies:
        description: Check for and install system dependencies
        required: false
        default: false
        type: boolean
      fail-pkgdown-on-warnings:
        description: Fail the pkgdown workflow if warnings are generated while generating docs
        required: false
        default: false
        type: boolean
      enable-staged-dependencies-check:
        description: Enable staged dependencies YAML check
        required: false
        default: false
        type: boolean
      additional-env-vars:
        description: |
          Extra environment variables, as a 'key=value' pair, with each pair on a new line.
          Example usage:
          additional-env-vars: |
            ABC=123
            XYZ=456
        required: false
        default: ""
        type: string
      refs-order:
        description: |
          The order in which refs should appear in the drop-down list. Versions not in the vector
          will appear below refs listed here.
          If docs have never been generated for the ref, the ref will not appear in the
          drop-down. Similarly, if docs have been generated for the ref, but the ref is not
          listed in the vector, it will not appear in the drop-down.
        required: false
        default: c("devel", "pre-release", "main", "latest-tag")
        type: string
      default-landing-page:
        description:
          The default branch or tag on gh-pages that corresponds to the landing page.
          For instance, if your root index page on gh-pages is built using the 'main'
          branch, then the root page of the website will correspond to this page.
          If 'latest-tag' is selected, then the latest version will become the default.
        required: false
        default: main
        type: string

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

jobs:
  docs:
    name: Generate 🐣
    runs-on: ubuntu-latest
    if: >
      !contains(github.event.commits[0].message, '[skip docs]')
        && github.event.pull_request.draft == false
    container:
      image: ghcr.io/insightsengineering/rstudio_4.2.2_bioc_3.16:latest
    steps:
      - name: Get branch names 🌿
        id: branch-name
        uses: tj-actions/branch-names@v6

      - name: Checkout repo (PR) 🛎
        uses: actions/checkout@v3
        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 }}

      - name: Checkout repo 🛎
        uses: actions/checkout@v3
        if: github.event_name != 'pull_request'
        with:
          ref: ${{ steps.branch-name.outputs.head_ref_branch }}
          path: ${{ github.event.repository.name }}

      - name: Restore SD cache 💰
        uses: actions/cache@v3
        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: ${{ secrets.REPO_GITHUB_TOKEN }}
        with:
          path: ${{ github.event.repository.name }}
          enable-check: ${{ inputs.enable-staged-dependencies-check }}
          run-system-dependencies: ${{ inputs.install-system-dependencies }}

      - name: Install R package 🚧
        run: |
          if (file.exists("renv.lock")) renv::restore()
          install.packages(".", repos=NULL, type="source")
        shell: Rscript {0}
        working-directory: ${{ github.event.repository.name }}

      - name: Build docs 🏗
        if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/v')
        run: |
          repo="${{ github.event.repository.name }}"
          if [ "${{ inputs.additional-env-vars }}" != "" ]
          then {
            echo -e "${{ inputs.additional-env-vars }}" > /tmp/dotenv.env
            export $(tr '\n' ' ' < /tmp/dotenv.env)
          }
          fi
          Rscript - <<EOF 2>&1 | tee pkgdown_${repo}.log
          if (file.exists("renv.lock")) renv::restore()
          pkgdown::build_site(devel = TRUE)
          EOF
          if [ "${{ inputs.fail-pkgdown-on-warnings }}" == "true" ]; then {
            grep "Warning message" pkgdown_${repo}.log > pkgdown_warnings_${repo}.log
            if [[ $(wc -l <pkgdown_warnings_${repo}.log) -gt 0 ]]; then {
              echo "----------------------------------------"
              echo "⚠ One or more warnings were generated during the pkgdown build."
              echo "Please 🙏 fix the warnings shown above 👆"
              exit 1
            }
            fi
          }
          fi
        shell: bash
        working-directory: ${{ github.event.repository.name }}

      - name: Create documentation artifact 📂
        if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/v')
        run: |
          pushd ${{ github.event.repository.name }}/docs/
          zip -r9 $OLDPWD/pkgdown.zip *
          popd
        shell: bash

      - name: Upload docs for review ⬆
        if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/v')
        uses: actions/upload-artifact@v3
        with:
          name: pkgdown.zip
          path: pkgdown.zip

      - name: Publish docs 📢
        if: github.event_name == 'push'
        run: |
          git config --local user.email "actions@github.com"
          git config --local user.name "GitHub Actions"
          BRANCH_OR_TAG="${GITHUB_REF##*/}"
          if [ "${{ inputs.additional-env-vars }}" != "" ]
          then {
            echo -e "${{ inputs.additional-env-vars }}" > /tmp/dotenv.env
            export $(tr '\n' ' ' < /tmp/dotenv.env)
          }
          fi
          Rscript - <<EOF
          if (file.exists("renv.lock")) renv::restore()
          pkgdown::deploy_to_branch(
            new_process = FALSE,
            subdir = "${BRANCH_OR_TAG}",
            clean = TRUE
          )
          EOF
        shell: bash
        working-directory: ${{ github.event.repository.name }}

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

      - name: Create and publish docs ↗️
        uses: insightsengineering/r-pkgdown-multiversion@v2
        with:
          path: ${{ github.event.repository.name }}
          default-landing-page: ${{ inputs.default-landing-page }}
          refs-order: ${{ inputs.refs-order }}

  upload-release-assets:
    name: Upload documentation assets 🔼
    needs: docs
    runs-on: ubuntu-latest
    if: >
      startsWith(github.ref, 'refs/tags/v')
        && !contains(github.event.commits[0].message, '[skip docs]')
    steps:
      - name: Checkout repo 🛎
        uses: actions/checkout@v3

      - name: Download artifact ⏬
        uses: actions/download-artifact@v3
        with:
          name: pkgdown.zip

      - name: Upload binaries to release ⤴
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: pkgdown.zip
          asset_name: pkgdown.zip
          tag: ${{ github.ref }}
          overwrite: true