Generating a website for your R package is always a great idea. If the package is based on some paper, it will help it get noticed and eventually used. And once you have a website, it’s just as well to include a reference manual for the package in it, that complements or is a bit more updated than the one published in CRAN. Or simply in another format.
That’s what I tried to do for my package dupNodes. I found pkgdown, an one-stop solution for generating websites, which even generates the GitHub action for you.
I had a problem, though. I already had some semblance of website, using Jekyll to generate the pages from markdown, and just plain HTML elsewhere, for presentations and other stuff. And pkgdown generated an index.html, overwriting at least the main stuff, and not including some images I had in the README.md file.
So I decided to combine both in the same workflow. Here’s what I had initially
on:
push:
branches: [“master”]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: “pages”
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
– name: Checkout
uses: actions/checkout@v4
– name: Setup Pages
uses: actions/configure-pages@v4
– name: Build with Jekyll
uses: actions/jekyll-build-pages@v1
with:
source: ./
destination: ./_site
This is the default GitHub action generated by GitHub itself, pretty vanilla stuff. What it says is that it generates the HTML stuff to be deployed in a subdirectory called _site.
So far so good. The only thing you have to do is to tell pkgdown to generate it stuff in the same directory (or subdirectory thereof), right?
Wrong. jekyll-build-pages uses a docker container for generating the image, and that one does not follow the best practice of using a non-privileged user. Everything generated in _site has root privileges, so pkgdown failed with an EACCESS error.
So I had to add this step after that:
run: sudo chown -R runner _site
Simple enough, but required some research to check who was the user running the GitHub action. After that, it was easy to incorporate the rest of the GitHub action, copypasta from the one generated by pkgdown itself:
– uses: r-lib/actions/setup-r@v2
with:
use-public-rspm: true
– uses: r-lib/actions/setup-r-dependencies@v2
with:
extra-packages: any::pkgdown, local::.
needs: website
– name: Build site
run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE, dest_dir=”_site/docs”)
shell: Rscript {0}
The only change over the original is the dest_dir right above this: it’s generated to _site/docs, within the _site directory that will be packaged for deployment.
Just one thing left. pkgdown does not seem to be aware of images linked from the README.md when it generates the cover for the site. So these had to be added too:
run: cp -r _site/img _site/docs/
– name: Upload artifact
uses: actions/upload-pages-artifact@v3
Initial version used symbolic links, but upload-pages-artifact choked on it, so I had to physically copy the directory.
And that’s it now. A website with reference and articles, updated automatically, without having to wait for CRAN updates!
