gha/examples/altdoc-multiversion-docs.yml at main · Morrison-Lab/gha · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
# Copy to .github/workflows/docs.yaml in your repo.
# NOTE: Do NOT name a `concurrency:` group `gh-pages` anywhere in this
# caller workflow -- neither a top-level block nor one on the calling job,
# which deadlock identically
# ([gha#811](https://github.com/Morrison-Lab/gha/pull/811)).
# Any OTHER group name is fine,
# and is how you serialize this workflow's own runs --
# with one exception for this capability.
# Its `build` job holds a second group that becomes
# `altdoc-multiversion-docs-<pr-number>` on a pull request
# and `altdoc-multiversion-docs-<ref>` on anything else,
# so do not prefix your own group with `altdoc-multiversion-docs-` at all:
# either spelling can resolve to the group the `build` job already holds.
# The reusable workflow serializes gh-pages deploys internally
# on its `deploy` job (`group: gh-pages`).
# A caller-level block with the same group name deadlocks GitHub Actions
# against the nested job:
# the job fails with no runner, no steps, and no log, so the site silently
# stops publishing ([gha#809](https://github.com/Morrison-Lab/gha/issues/809)).
#
# Renders an altdoc-based R package's Quarto docs and deploys multiple
# versions side by side on gh-pages: PRs -> /pr-preview/pr-<number>/, pushes
# to the default branch -> /dev/, published releases -> /latest-tag/ and
# /vX.Y.Z/. The calling job must grant contents: write (the deploy steps push
# to gh-pages) and pull-requests: write + issues: write (the PR-preview
# sticky comment and "Report an issue" link rewrite).
#
# One-time repo setup: Settings -> Pages -> Build and deployment -> Source =
# "Deploy from a branch", branch `gh-pages` / `(root)`.
#
# Requires an altdoc/quarto_website.yml navbar with a "Versions" menu entry
# for the version-dropdown step to rewrite, e.g.:
#   navbar:
#     right:
#       - text: Versions
#         menu:
#           - text: "$ALTDOC_PACKAGE_VERSION (dev)"
#             href: https://<owner>.github.io/<repo>/dev/
name: Docs

on:
  push:
    branches: [main]
  release:
    types: [published]
  pull_request:
    types: [opened, reopened, synchronize, closed]
  workflow_dispatch:
    inputs:
      version:
        description: Documentation version to deploy
        required: true
        default: dev
        type: choice
        options:
          - dev
          - stable
      release_tag:
        description: Stable release tag to deploy when version=stable (e.g. v1.2.3)
        required: false
        type: string

jobs:
  docs:
    permissions:
      contents: write
      pull-requests: write
      issues: write
    uses: Morrison-Lab/gha/.github/workflows/altdoc-multiversion-docs.yml@v2
    with:
      dispatch-version: ${{ github.event.inputs.version }}
      dispatch-release-tag: ${{ github.event.inputs.release_tag }}
      # r-packages: |               # override if you need a fork of altdoc
      #   any::altdoc
      #   quarto-dev/quarto-r
      #   any::sessioninfo
      #   local::.
      # needs: |                     # r-lib/actions/setup-r-dependencies needs list
      #   connect
      #   website
      # apt-packages: ''             # extra apt packages before rendering
      # setup-julia: false           # set true for packages with a JuliaCall dependency
      # checkout-submodules: 'recursive'  # 'recursive' | 'true' | 'false'
      # default-branch: main
      # quarto-config-path: altdoc/quarto_website.yml
      # docs-base-url: ''            # override; default derives from this repo
      # preview-branch: gh-pages
      # timeout-minutes: 30
      # rewrite-pr-preview-links: true
      # rewrite-issue-links: true
      # legacy-paths: main=dev      # redirect retired version dirs, e.g. a
      #                             # site that used to publish the default
      #                             # branch's docs to /main/ instead of /dev/
      # root-landing-target: latest-tag
      #                             # pin the site root's redirect to the
      #                             # released docs, instead of letting each
      #                             # deploy point it at whatever it built
      # version-dropdown-title-template: '{version}'  # navbar Versions menu
      #                             # label; "{version}" is the version being
      #                             # rendered, e.g. "v1.2.3 (stable)". Try
      #                             # 'Version: {version}' to keep a word.
      # version-in-navbar-title: true  # show that version next to the navbar
      #                             # title, the way pkgdown does