pkgdown multiversion

.github/workflows/pkgdown.yaml

@@ -1,28 +1,52 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
-# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+# Deploys pkgdown for Pull Requests, tags, and pushes to main branch
+# PRs are deployed to /preview/pr<number>/
+# Tags are deployed to /<tag>/
 on:
-  push:
-    branches: [main, master]
   pull_request:
-    branches: [main, master]
-  release:
-    types: [published]
+    branches:
+      - main
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - 'man/**'
+      - 'pkgdown/**'
+      - 'vignettes/**'
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'         # build on version tags
+      - '!v[0-9]+.[0-9]+.[0-9]+.[0-9]+' # but not if version involves a dev component
+    branches:
+      - main
   workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to deploy
+        required: true
+        default: ''
 
 name: pkgdown
 
 jobs:
-  pkgdown:
+  pkgdown-build:
     runs-on: ubuntu-latest
-    # Only restrict concurrency for non-PR jobs
-    concurrency:
-      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-    permissions:
-      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v2
+
+      - name: Configure git
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+      - uses: r-lib/actions/pr-fetch@v2
+        if: ${{ github.event_name == 'pull_request' }}
+        with:
+          repo-token: ${{ github.token }}
 
       - uses: r-lib/actions/setup-pandoc@v2
 
@@ -32,17 +56,91 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::pkgdown, local::.
-          needs: website
+          needs: |
+            connect
+            website
+          extra-packages: |
+            local::.
+            any::pkgdown
+
+      # If events is a PR, set subdir to 'preview/pr<pr_number>'
+      - name: "[PR] Set documentation subdirectory"
+        if: github.event_name == 'pull_request'
+        run: |
+          echo "PKGDOWN_DEV_MODE=unreleased" >> $GITHUB_ENV
+          echo "subdir=preview/pr${{ github.event.number }}" >> $GITHUB_ENV
 
-      - name: Build site
-        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+      # If event is a tag, set subdir to '<tag_name>'
+      - name: "[tag] Set documentation subdirectory"
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          echo "PKGDOWN_DEV_MODE=release" >> $GITHUB_ENV
+          echo "subdir=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      # If event is workflow_dispatch, set subdir to 'inputs.tag'
+      - name: '[dispatch] Set documentation subdirectory'
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          echo "subdir=${{ github.event.inputs.tag }}" >> $GITHUB_ENV
+
+      - name: Deploy pkgdown site
+        id: deploy
         shell: Rscript {0}
+        run: |
+          subdir <- "${{ env.subdir }}"
+          pkg <- pkgdown::as_pkgdown(".")
+
+          # Deploy pkgdown site to branch
+          pkgdown::deploy_to_branch(subdir = if (nzchar(subdir)) subdir, clean = nzchar(subdir))
+
+          # Report deployed site URL
+          deployed_url <- file.path(pkg$meta$url, subdir)
+          cat(sprintf('url=%s', deployed_url), file = Sys.getenv("GITHUB_OUTPUT"), append = TRUE)
+
+      - name: Notify pkgdown deployment
+        if: github.event_name == 'pull_request'
+        uses: hasura/comment-progress@v2.2.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: pkgdown-deploy
+          append: false
+          message: >
+            :book: ${{ steps.deploy.outputs.url }}
+
+            Preview documentation for this PR (at commit ${{ github.event.pull_request.head.sha }})
+
+  pkgdown-clean:
+    if: ${{ github.event_name == 'pull_request' && github.event.action == 'closed' }}
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          ref: "gh-pages"
+
+      - name: Clean up PR Preview
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+          preview_dir="preview/pr${{ github.event.pull_request.number }}"
+          if [ -d "$preview_dir" ]; then
+            git rm -r $preview_dir
+            git commit -m "Remove $preview_dir (GitHub Actions)" || echo 'No preview to remove'
+            git push origin || echo 'No preview to remove'
+          else
+            echo 'No preview to remove'
+          fi
 
-      - name: Deploy to GitHub pages 🚀
-        if: github.event_name != 'pull_request'
-        uses: JamesIves/github-pages-deploy-action@v4.5.0
+      - name: Notify pkgdown cleanup
+        uses: hasura/comment-progress@v2.2.0
         with:
-          clean: false
-          branch: gh-pages
-          folder: docs
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: pkgdown-deploy
+          message: |
+            _:closed_book: Preview documentation for this PR has been cleaned up._

pkgdown/assets/doc-versions.json

@@ -0,0 +1,63 @@
+[
+	{
+		"text": "Latest",
+		"version": "0.1.3",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/"
+	},
+	{
+		"text": "Development",
+		"version": "0.1.3.9000",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/dev/",
+		"banner": {
+			"html": "This is the development version of {tfrmt}. View the <a>latest release</a>.",
+			"class": "alert-warning"
+		}
+	},
+	"---",
+	"Releases",
+	{
+		"text": "v0.1.2",
+		"version": "0.1.2",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/v0.1.2/",
+		"banner": {
+			"html": "A <a>newer version of {tfrmt}</a> is available!",
+			"class": "alert-info"
+		}
+	},
+	{
+		"text": "v0.1.1",
+		"version": "0.1.1",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/v0.1.1/",
+		"banner": {
+			"html": "A <a>newer version of {tfrmt}</a> is available!",
+			"class": "alert-info"
+		}
+	},
+		{
+		"text": "v0.1.0",
+		"version": "0.1.0",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/v0.1.0/",
+		"banner": {
+			"html": "A <a>newer version of {tfrmt}</a> is available!",
+			"class": "alert-info"
+		}
+	},
+		{
+		"text": "v0.0.3",
+		"version": "0.0.3",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/v0.0.3/",
+		"banner": {
+			"html": "A <a>newer version of {tfrmt}</a> is available!",
+			"class": "alert-info"
+		}
+	},
+		{
+		"text": "v0.0.2",
+		"version": "0.0.2",
+		"url": "https://gsk-biostatistics.github.io/tfrmt/v0.0.2/",
+		"banner": {
+			"html": "A <a>newer version of {tfrmt}</a> is available!",
+			"class": "alert-info"
+		}
+	}
+]