Add version switcher to the site

[TymekDev]

Changes

Closes #530

This script provides a function for building a pkgdown site with multiple versions.

Versions are defined by:

• ref - a git ref to build. In the gist, prefix tags with refs/tags/ and branches with refs/remotes/origin/
• href - a URL path where the version will be available at
• label - a label to display in a version switcher. Using true will take version from DESCRIPTION and append "(dev)" suffix

The script works as follows:

1. Copy repository into a temporary directory
2. Read pkgdown/navbar_template.html and populate switcher options with versions
3. For every version¹:
   a. Create a git worktree based on version's ref
   b. Populate the navbar template with current version's label
   c. Write the navbar template to pkgdown/templates/navbar.html relative to the git worktree
   d. Copy pkgdown/extra.css from the repository we are building out of (this ensures a consistent and up-to-date styling)
   e. Use pkgdown to build site
   f. Remove the worktree

The resulting build has the site with "/" href in the destination directory. Respective versions are stored in subdirectories named after labels defining versions.

Known issues

1. Every version has its own sitemap.xml
2. Every version has separate assets (Bootstrap, favicons, ...)
3. All versions are indexed by search engines
4. None of the versions has canonical URLs
5. "Source" link in vignettes and function reference is hardcoded to HEAD (instead of a respective version)
6. Switching a version redirects to index (instead of staying on the same subpage in target version if it exists)
7. Rhinoverse button resembling a back button makes is even more confusing. Pressing it neither puts you back to the default version nor to a root of the current version you are viewing. It sends you to an entirely new website.

To address 1.-4. it's best to contribute directly to pkgdown. I think the effort of adjusting this script and keeping relevant templates up-to-date would be bigger than implementing a proper version support directly in pkgdown.

Additionally, I pinned bslib version to keep Bootstrap 5.2.2. Using latest bslib that provides Bootstrap 5.3.0 resulted in styling partially breaking on the site. However, the styling altogether should be revisited and improved.

How to test

1. Visit https://tymekdev.github.io/rhino
2. Use the switcher in the navbar
3. Observe how content and URL changes after selecting a new version

Footnotes

1. Version with "/" href will be built first. This avoids an error from pkgdown regarding building the site to a non-empty directory (that's not managed by pkgdown). ↩

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 20.65%. Comparing base (82476b5) to head (61cddfd).
Report is 8 commits behind head on main.

❗ Current head 61cddfd differs from pull request most recent head fd5a656

Please upload reports for the commit fd5a656 to get more accurate results.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #575       +/-   ##
===========================================
- Coverage   38.55%   20.65%   -17.91%     
===========================================
  Files          10        9        -1     
  Lines         594      460      -134     
===========================================
- Hits          229       95      -134     
  Misses        365      365               

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[TymekDev]

I just realized that with this change we should build pkgdown on push to main. This way documentation of the development version stays up to date.

Thoughts?

[kamilzyla]

Awesome! 💯 It's all working pretty great. The only must-have changes are: workflow configuration (run on push to main) and styling issue (white box). Treat my remaining comments as suggestions.

It would be possible to inject the version switcher using before_navbar (see this commit) to get a perhaps cleaner solution. You can use it if you want or I could send you a follow-up PR 😉

[kamilzyla]

LGTM, great work! 🎉 💯

[kamilzyla]

My notes from the review for future reference:

1. It seems there is no clean way to git-checkout files without creating a worktree.
2. The solution uses the same pkgdown version for the whole documentation. It’s OK.
3. Subtle: For dev version we call desc_get_version() in the currently checked-out repo which could be different from the ref defined in versions.yaml.

Ideas for improvements:

1. Use before_navbar (append - do not replace).
2. Build versions in parallel?
3. Use robots.txt to ignore older versions?