Documentation #84
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | |
| 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/[email protected] | |
| - name: Checkout repo (PR) 🛎 | |
| uses: actions/checkout@v3 | |
| 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@v3 | |
| 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} | |
| } | |
| R_VERSION=$(normalize ${{ inputs.r-version }} 4.1) | |
| DOCS_LANDING_PAGE=$(normalize ${{ inputs.multiversion-docs-landing-page }} main) | |
| echo "R_VERSION=$R_VERSION" >> $GITHUB_OUTPUT | |
| echo "DOCS_LANDING_PAGE=$DOCS_LANDING_PAGE" >> $GITHUB_OUTPUT | |
| shell: bash | |
| - name: Restore cache | |
| uses: actions/cache@v3 | |
| 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 | |
| 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/[email protected]" | |
| 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() | |
| } | |
| 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 "[email protected]" | |
| git config --local user.name "GitHub Actions" | |
| SUBDIR_OPTION="" | |
| if [ "${{ inputs.skip-multiversion-docs }}" != "true" ] | |
| then { | |
| SUBDIR_OPTION="subdir = \"${GITHUB_REF##*/}\"," | |
| } | |
| fi | |
| Rscript - <<EOF | |
| 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@v3 | |
| 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 | |
| shell: bash | |
| - name: Create and publish docs | |
| uses: insightsengineering/r-pkgdown-multiversion@v2 | |
| 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 }} |