Migrate docs.yaml to consume gha's new altdoc-multiversion-docs capability

[d-morrison]

Summary

d-morrison/gha#284 ports this
repo's bespoke .github/workflows/docs.yaml (multiversion altdoc docs: dev/
latest-tag/vX.Y.Z + PR previews + root redirect) into a reusable gha
capability (altdoc-multiversion-docs.yml, plus the two internal composites
generate-altdoc-version-dropdown / generate-altdoc-landing-page), so that
altdoc-based R packages -- including future packages created from this
template -- don't each carry their own copy of the version-dropdown and
landing-page scripts.

This repo (rpt), as the source of the pattern, is the natural first
consumer to switch over, dropping .github/scripts/generate_version_dropdown.py,
.github/scripts/generate_multiversion_landing_page.py, and most of
.github/workflows/docs.yaml in favor of a small caller stub (see
examples/altdoc-multiversion-docs.yml
once #284 merges and @v2 is advanced to include it).

Why not done now

Two open PRs -- #166 and #167 -- are actively editing
generate_version_dropdown.py / docs.yaml right now. Migrating this repo
onto the gha capability at the same time would collide with both. Deferring
until:

1. #284 merges into d-morrison/gha and @v2 is advanced (or this repo
   pins a specific commit/branch in the interim).
2. Fix hard-coded docs base URL in version dropdown generator #166/Rewrite legacy docs links in docs deploy workflow #167 are resolved (note: Fix hard-coded docs base URL in version dropdown generator #166 looks like it may already be
   superseded by Fix hard-coded docs base URL in version dropdown generator #165's own fix to the same hard-coded-BASE_URL bug --
   worth a look before continuing it).

Feature-parity checklist for whoever does the migration

Per this repo's own CLAUDE.md guidance on migrating a bespoke workflow to
a reusable one ("needs a feature-by-feature diff, not just a structural
read"), confirm each of these carries over, not just the high-level shape:

• Version dropdown generation (stable/dev/previous tags)
• Root landing-page redirect
• PR-preview deploy and removal on close (note: rpt's original
  docs.yaml job-level if: skipped the whole job on PR close, so the
  preview directory was never actually removed -- gha#284's port fixes
  this; migrating rpt picks up the fix)
• /latest-tag/ bootstrap-if-missing on first rollout
• workflow_dispatch manual dev/stable redeploy, including the stable-tag
  worktree checkout
• PR-preview repo-link rewriting (Edit this page / View source / GitHub icon)
• "Report an issue" link repointing
• Optional Julia setup (rpt's docs.yaml has a "Set up Julia" step with
  no corresponding DESCRIPTION dependency -- confirm whether this repo
  actually needs it before/after the migration, since the gha version
  makes it an opt-in setup-julia input defaulting to false)

[d-morrison]

One more thing this repo gains on migrating:
d-morrison/gha#308 makes the
navbar name the version being viewed -- the "Versions" menu is labeled with
it (v1.2.3 (stable), 0.1.0.9000 (dev)), and the navbar title carries it
beside the package name the way pkgdown does.

It was developed against this repo's own altdoc/quarto_website.yml as the
realistic fixture, so no config change is needed here beyond the migration
itself: the existing - text: Versions entry is still the anchor the
composite rewrites.

Worth adding to the feature-parity checklist above as a gain rather than a
parity item, since this repo's bespoke
.github/scripts/generate_version_dropdown.py does not do it.

---

Generated by Claude Code

[d-morrison]

Both stated blockers now look clear:

1. gha#284 merged and @v2 advanced. altdoc-multiversion-docs is
   listed among the @v2 capabilities in gha's README.md, and
   examples/altdoc-multiversion-docs.yml is available to copy.
2. Fix hard-coded docs base URL in version dropdown generator #166/Rewrite legacy docs links in docs deploy workflow #167 are resolved. This repo has zero open PRs as of now, so
   nothing is editing generate_version_dropdown.py or docs.yaml
   concurrently -- the collision risk that deferred this is gone.

Two things worth folding into the parity checklist above before starting:

• The capability has moved ahead of what this repo does.
  gha#308 (open) makes the
  navbar name the version being viewed and adds a pkgdown-style version
  badge; gha#301 added legacy-paths redirects. Migrating picks both up,
  neither of which the bespoke scripts here do.
• in docs workflow, cache dependencies immediately after installing them #126 should be folded in, not done first -- see my note there. It
  proposes restructuring the dependency-cache step in a docs.yaml this
  migration mostly deletes.

I have not started this; flagging the unblock so whoever picks it up does not
re-derive it. It is the largest remaining item in this repo's queue and the
one with a real feature-parity risk, so it wants a deliberate session rather
than a sweep.

---

Generated by Claude Code