Switch from pkgdown to altdoc for documentation by Copilot · Pull Request #503 · UCD-SERG/serocalculator

Copilot · 2026-02-02T05:58:12Z

Description

Replaces pkgdown with altdoc following the UCD-SERG/rpt pattern. Documentation renders with Quarto via altdoc::render_docs().

Changes:

DESCRIPTION: Added altdoc, bslib to Suggests; updated Config/Needs/website with d-morrison/altdoc@recursive-qmd-search remote
altdoc/ directory created:
- quarto_website.yml: Quarto config using altdoc template variables ($ALTDOC_PACKAGE_NAME, $ALTDOC_PACKAGE_URL_GITHUB, $ALTDOC_MAN_BLOCK) with proper sections/contents structure for navbar
- index.qmd: Includes README.md
- CONTRIBUTING.md: Includes .github/CONTRIBUTING.md
- styles.css: Custom sidebar spacing
- .gitignore: Ignores altdoc/ directory
.github/workflows/docs.yaml:
- Workflow name "Docs 📚" restored
- Uses altdoc::render_docs() instead of pkgdown::build_site()
- Workflow elements reordered to match main branch structure (push, release, pull_request, workflow_dispatch)
- Added cancel-in-progress: true to concurrency settings
- Removed duplicate name key
.Rbuildignore: Added ^altdoc$, removed pkgdown-specific patterns
vignettes/_metadata.yml: Created with format settings extracted from _quarto.yml
Removed files: pkgdown/ directory, _quarto.yml from repo root

Maintained:

PR preview deployment to /preview/pr<number>/
GitHub Pages deployment for main branch and version tags
Output to docs/ directory
Support for .Rmd and .qmd vignettes

Configuration:

Bootstrap 5 with light/dark theme toggle
Downlit code-linking enabled
Bibliography from vignettes/references.bib
Navbar uses proper sections with contents arrays (Get started, Methodology, Examples)
Sidebar sections: Home, Articles (Get started/Methodology/Examples), Reference, News, Code of Conduct, Contributing

Note on Multi-version Documentation:

The insightsengineering/r-pkgdown-multiversion action is not compatible with altdoc as it is specifically designed for pkgdown sites and expects pkgdown's output structure. Multi-version documentation support was removed. Implementing multi-version docs with altdoc would require a custom workflow solution.

The title of your PR should briefly describe the change.
Commit/merge messages to be included in NEWS.md should begin with -.
Code should follow the tidyverse style guide.
Documentation should use roxygen2, with Markdown syntax.
Contributions should include unit tests (using testthat). - N/A for infrastructure change

For more information see Contributing.

Original prompt

This section details on the original issue you should resolve

<issue_title>switch to altdoc</issue_title>
<issue_description>follow the example of https://github.com/d-morrison/altdoc</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes switch to altdoc #502

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

… quarto package reference Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

… navbar structure, extract _quarto.yml to vignettes/_metadata.yml Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Copilot · 2026-02-02T06:42:47Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/repos/UCD-SERG/rpt/contents/vignettes
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

codecov · 2026-02-02T07:45:13Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

d-morrison · 2026-02-02T07:47:48Z

  pull_request:
    types:
      - opened
-      - synchronize
      - reopened
-      - ready_for_review
+      - synchronize
      - closed
+    paths:
+      - 'man/**'
+      - 'altdoc/**'
+      - 'vignettes/**'
+      - '.github/workflows/docs.yaml'
+      - 'README.md'
+      - 'index.qmd'
+  push:
+    tags:
+      - 'v[0-9]+\.[0-9]+\.[0-9]+'  # build on version tags like v1.2.3
    branches:
      - main
-    paths:
-      - "inst/templates/**"
-      - "pkgdown/**"
-      - "_pkgdown.*"
-      - DESCRIPTION
-      - "**.md"
-      - "**.Rmd"
-      - "man/**"
-      - "LICENSE.*"
-      - NAMESPACE
-      - ".github/workflows/docs.yaml"
+  release:
+    types: [published]
  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to deploy
+        required: false
+        default: ''
+
+name: docs


reorder these elements to match the main branch version order as closely as possible, so the diff is easier to read

Done in acd0e64. Reordered to match main branch: push (with branches, tags, paths), release, pull_request (with types, branches, paths), workflow_dispatch.

d-morrison · 2026-02-02T07:48:18Z

  pull_request:
    types:
      - opened
-      - synchronize
      - reopened
-      - ready_for_review
+      - synchronize
      - closed
+    paths:
+      - 'man/**'
+      - 'altdoc/**'
+      - 'vignettes/**'
+      - '.github/workflows/docs.yaml'
+      - 'README.md'
+      - 'index.qmd'
+  push:
+    tags:
+      - 'v[0-9]+\.[0-9]+\.[0-9]+'  # build on version tags like v1.2.3
    branches:
      - main
-    paths:
-      - "inst/templates/**"
-      - "pkgdown/**"
-      - "_pkgdown.*"
-      - DESCRIPTION
-      - "**.md"
-      - "**.Rmd"
-      - "man/**"
-      - "LICENSE.*"
-      - NAMESPACE
-      - ".github/workflows/docs.yaml"
+  release:
+    types: [published]
  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to deploy
+        required: false
+        default: ''
+
+name: docs


remove duplicate name key

Done in acd0e64. Removed duplicate name: docs on line 37.

d-morrison · 2026-02-02T07:48:54Z


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


keep the cancel-in-progress rule for concurrency

Done in acd0e64. Added cancel-in-progress: true to the concurrency section.

…rogress Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Initial plan

8d90279

Copilot AI assigned Copilot and d-morrison Feb 2, 2026

Copilot started work on behalf of d-morrison February 2, 2026 05:58 View session

Copilot AI and others added 10 commits February 2, 2026 06:03

Add altdoc configuration and update workflow

dd18661

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix vignette file extensions in altdoc config

35ee89c

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Add CONTRIBUTING.md to altdoc sidebar

173f86a

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix workflow issues identified in code review

d7dc6e4

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix concurrency group and YAML indentation in workflow

60f5631

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Improve GitHub link aria-label for accessibility

fbe5c92

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix data-raw exclusion pattern, use altdoc variable for repo URL, fix…

8af40c4

… quarto package reference Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix YAML indentation in commented env section

512421c

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Fix tag pattern to escape periods in version regex

6bd2a3f

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Remove unsupported negation pattern from tag filter

7a35113

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Switch to altdoc implementation~~ Switch from pkgdown to altdoc for documentation Feb 2, 2026

Copilot AI requested a review from d-morrison February 2, 2026 06:16

Copilot finished work on behalf of d-morrison February 2, 2026 06:16

d-morrison requested changes Feb 2, 2026

View reviewed changes

Comment thread .Rbuildignore Outdated

Comment thread .github/workflows/docs.yaml

Comment thread .github/workflows/docs.yaml

Comment thread altdoc/.gitignore Outdated

Comment thread altdoc/quarto_website.yml Outdated

Copilot started work on behalf of d-morrison February 2, 2026 06:37 View session

Address PR feedback: remove pkgdown files, add multiversion docs, fix…

fc902a8

… navbar structure, extract _quarto.yml to vignettes/_metadata.yml Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Copilot AI requested a review from d-morrison February 2, 2026 06:43

Copilot finished work on behalf of d-morrison February 2, 2026 06:43

d-morrison requested changes Feb 2, 2026

View reviewed changes

Comment thread .github/workflows/docs.yaml

Copilot started work on behalf of d-morrison February 2, 2026 06:53 View session

Remove r-pkgdown-multiversion job (incompatible with altdoc)

2bd2597

Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Copilot AI requested a review from d-morrison February 2, 2026 06:58

Copilot finished work on behalf of d-morrison February 2, 2026 06:58

d-morrison added no changelog no version increment labels Feb 2, 2026

d-morrison mentioned this pull request Feb 2, 2026

build altdoc multi-version-docs approach #504

Open

d-morrison requested changes Feb 2, 2026

View reviewed changes

Copilot started work on behalf of d-morrison February 2, 2026 07:49 View session

Reorder workflow elements, remove duplicate name key, add cancel-in-p…

acd0e64

…rogress Co-authored-by: d-morrison <2474437+d-morrison@users.noreply.github.com>

Copilot AI requested a review from d-morrison February 2, 2026 07:54

Copilot finished work on behalf of d-morrison February 2, 2026 07:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch from pkgdown to altdoc for documentation#503

Switch from pkgdown to altdoc for documentation#503
Copilot wants to merge 14 commits intomainfrom
copilot/switch-to-altdoc

Copilot AI commented Feb 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Feb 2, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

codecov Bot commented Feb 2, 2026

Uh oh!

d-morrison Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

d-morrison Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

d-morrison Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Comments on the Issue (you are @copilot in this section)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Feb 2, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

codecov Bot commented Feb 2, 2026

Codecov Report

Uh oh!

d-morrison Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

d-morrison Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

d-morrison Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 2, 2026 •

edited

Loading