Add multi-version pkgdown documentation with version dropdown menu#173
Add multi-version pkgdown documentation with version dropdown menu#173
Conversation
Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
- Update actions/download-artifact from v4 to v4.1.8 (fixes CVE-2024-42471: arbitrary file write) - Update actions/checkout from v4 to v4.3.1 (latest stable v4) - Update actions/upload-artifact from v4 to v4.6.2 (latest stable v4) Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
d-morrison
left a comment
d-morrison
left a comment
There was a problem hiding this comment.
add pr preview to docs workflow
PR preview functionality is already implemented in the docs.yaml workflow (lines 226-273). It deploys PR previews to Could you clarify what specific change you'd like regarding PR previews? For example:
|
d-morrison
left a comment
d-morrison
left a comment
There was a problem hiding this comment.
make sure the docs workflow runs when it is modified
Ensure the docs workflow runs when .github/workflows/docs.yaml is modified, allowing workflow changes to be tested automatically on PRs and pushes. Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Added |
d-morrison
left a comment
d-morrison
left a comment
There was a problem hiding this comment.
docs workflow still didn't run; fix
Path filters were preventing the workflow from running reliably. Removing them ensures the workflow runs on all PR and push events, which is needed for testing workflow changes. Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Removed path filters from the docs workflow in commit c4ca44d. The workflow will now run on all PR and push events, ensuring it executes whenever the workflow file is modified. Path filters were preventing reliable workflow execution. |
d-morrison
left a comment
d-morrison
left a comment
There was a problem hiding this comment.
put the path filters back and remove the requirement that the pr is not a draft
|
📖 https://ucdavis.github.io/serodynamics/preview/pr173/ |
- Restored path filters for push and pull_request events to optimize workflow execution - Removed draft PR check to allow workflow to run on draft PRs - Workflow now runs when documentation-related files or the workflow file itself is modified Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Restored path filters and removed draft PR check in commit cf0c771. The workflow will now:
|
There was a problem hiding this comment.
Pull request overview
This PR implements multi-version pkgdown documentation with a version dropdown menu, replacing the previous single-version setup. The implementation is based on the insightsengineering/tern reference setup and uses the insightsengineering/r-pkgdown-multiversion@v3 action to provide version navigation.
Key changes:
- New comprehensive
docs.yamlworkflow with 4 jobs for building docs, creating multi-version navigation, uploading release assets, and cleaning up PR previews - Removal of the old
pkgdown.yamlworkflow - Documentation for the new multi-version setup in
.github/MULTI_VERSION_DOCS.md
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
.github/workflows/docs.yaml |
New multi-version documentation workflow replacing pkgdown.yaml, with jobs for building docs, version navigation, release asset uploads, and PR preview cleanup |
.github/workflows/pkgdown.yaml |
Removed old single-version pkgdown workflow |
.github/MULTI_VERSION_DOCS.md |
Comprehensive documentation explaining the multi-version setup, features, configuration, and troubleshooting |
NEWS.md |
Added entry documenting the new multi-version documentation feature |
| - main | ||
| paths: |
There was a problem hiding this comment.
The condition !contains(github.event.commits[0].message, '[skip docs]') may fail when the workflow is triggered by tag pushes or workflow_dispatch, because the github.event.commits array might not exist in these contexts. Consider using github.event.head_commit.message instead, which is more reliable across different event types, or wrap the check in a condition that only applies to push events on branches.
| sudo apt-get update | ||
| sudo apt-get install -y jags libcurl4-openssl-dev | ||
| shell: bash | ||
|
|
There was a problem hiding this comment.
The pkgdown::build_site() call uses devel = TRUE for all builds, including tagged releases. For version tags (releases), you typically want devel = FALSE to indicate it's a released version, not a development version. Consider adding conditional logic to set devel = FALSE when building documentation for version tags, and devel = TRUE only for PRs and main branch builds.
| ### Path Filtering | ||
| The workflow only runs when these files change: | ||
| - `inst/templates/**` | ||
| - `pkgdown/**` | ||
| - `_pkgdown.*` | ||
| - `DESCRIPTION` | ||
| - `**.md`, `**.Rmd` | ||
| - `man/**` | ||
| - `LICENSE.*` | ||
| - `NAMESPACE` | ||
|
|
There was a problem hiding this comment.
The documentation states that the workflow has path filtering, but the actual workflow file (docs.yaml) does not have any path filters in its trigger configuration. Lines 104-112 in this documentation file should be removed as they are inaccurate. The PR description correctly mentions "No path filtering: Workflow runs on all PR and push events for reliable execution", which aligns with the actual workflow implementation.
| ### Path Filtering | |
| The workflow only runs when these files change: | |
| - `inst/templates/**` | |
| - `pkgdown/**` | |
| - `_pkgdown.*` | |
| - `DESCRIPTION` | |
| - `**.md`, `**.Rmd` | |
| - `man/**` | |
| - `LICENSE.*` | |
| - `NAMESPACE` |
|
|
||
| - name: Get current branch or tag 🏷️ | ||
| id: current-branch-or-tag | ||
| run: | | ||
| if [ "${{ steps.branch-name.outputs.is_tag }}" == "true" ]; then | ||
| echo "Current tag: ${{ steps.branch-name.outputs.tag }}" |
There was a problem hiding this comment.
When the workflow is triggered by a tag push, using steps.branch-name.outputs.current_branch as the ref may not work correctly since tags don't have a "current_branch". For tag events, the ref should be the tag itself. Consider modifying the checkout to handle tags explicitly, similar to how it's done in the "Get current branch or tag" step above. A better approach would be to use the output from that step (steps.current-branch-or-tag.outputs.ref-name) or to add a separate checkout step for tags that uses the tag ref directly.
| echo "url=https://${REPO_OWNER}.github.io/${REPO_NAME}/${PREVIEW_DIR}/" >> $GITHUB_OUTPUT | ||
| shell: bash | ||
|
|
There was a problem hiding this comment.
The condition !contains(github.event.commits[0].message, '[skip docs]') may fail when the workflow is triggered by workflow_dispatch or tag pushes, because the github.event.commits array might not exist or be structured differently in these contexts. Consider using a safer condition that handles cases where commits might not be available, or move the commit message check to only run when it's applicable (push events on branches). Alternatively, use github.event.head_commit.message which is more reliable across different event types.
| (github.event_name == 'push' || github.event_name == 'workflow_dispatch') | ||
| && !contains(github.event.commits[0].message, '[skip docs]') | ||
| steps: |
There was a problem hiding this comment.
The condition !contains(github.event.commits[0].message, '[skip docs]') may fail for tag push events because the github.event.commits array might not exist or be structured differently when pushing tags. Consider using github.event.head_commit.message instead, or remove this check for tag-specific jobs since tags are deliberate version releases where you'd always want documentation built.
d-morrison
left a comment
d-morrison
left a comment
There was a problem hiding this comment.
why doesn't the version selector drop down menu appear in the preview?
The version dropdown menu only appears on the deployed versioned documentation (main branch and release tags), not in PR previews. This is by design:
PR previews are temporary and meant for reviewing documentation changes before merging. Once the PR is merged to main or a version tag is created, the To see the version dropdown:
|
- Fix commit message check to use github.event.head_commit.message (more reliable across event types) - Fix tag checkout to use the ref-name output from current-branch-or-tag step - Add conditional logic for pkgdown devel parameter: FALSE for version tags, TRUE for dev builds - Remove redundant commit message checks from jobs that depend on the docs job - Addresses code review feedback for better workflow reliability Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>
Implementation Complete ✅
Successfully implemented multi-version pkgdown documentation with version dropdown menus, matching the insightsengineering/tern setup.
What was implemented
.github/workflows/docs.yamlworkflow with multi-version supportpkgdown.yamlwith comprehensive workflow.github/MULTI_VERSION_DOCS.mdSecurity Fixes Applied
Updated all GitHub Actions to latest stable v4 versions:
actions/download-artifact: v4 → v4.1.8
actions/checkout: v4 → v4.3.1 (latest stable v4)
actions/upload-artifact: v4 → v4.6.2 (latest stable v4)
Key Features
1. Multi-version documentation
insightsengineering/r-pkgdown-multiversion@v3actionlatest-tag(most recent release)devel = FALSEfor releases,devel = TRUEfor development2. Version dropdown
main,latest-tag, and version tags (v*..)mainfirst, thenlatest-tag, then other versions^main$|^latest-tag$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$3. PR preview functionality
preview/pr<number>directories4. Automated deployment
inst/templates/**,pkgdown/**,_pkgdown.*DESCRIPTION,**.md,**.Rmdman/**,LICENSE.*,NAMESPACE.github/workflows/docs.yaml5. Release integration
Workflow Jobs
Files Changed
.github/workflows/docs.yaml(new)pkgdown.yamldevelparameter for proper version labelingNEWS.md(updated).github/MULTI_VERSION_DOCS.md(new)Prerequisites Verified ✅
pkgdown/_pkgdown.ymlhasbootstrap: 5pkgdown/_pkgdown.ymlhasurlfieldDESCRIPTIONhasURLfield with pkgdown site URLUser Experience
When visiting https://ucd-serg.github.io/serodynamics/, users will see:
Note on PR Previews: PR previews are standalone documentation builds for reviewing changes. They do not include the version dropdown menu - that only appears after merging to main or creating a version tag.
Next Steps
v0.1.0) to test version-specific documentation with dropdownSee
.github/MULTI_VERSION_DOCS.mdfor complete documentation on using the new setup.Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.