Generate pkgdown documentation

Automate creation and deployment of R package documentation

About the gh-action

Example of use: falcon R package

Expected output: Generate and deploy to gh-pages versioned documentation, and upload copy of documentation to release.

Why should I use this?

pkgdown is the most common framework for rendering R package documentation into a an HTML website. This gh-action will generate the documentation, and deploy it to a gh-pages branch. It will also upload a copy of the documentation to the release.

This is important for multiple reasons:

1. Because the documentation is generated automatically, you can make sure the documentation matches the code. Without CICD you are relying on users remembering to rebuild the documentation when they make changes.
2. If you manually generate the documentation, you will need to store the built artefacts in your git repo. This will bloat your repo, and make it harder to work with.
3. Because the documentation is versioned, you can always find the documentation that matches the version of the code you are using. This is important for reproducibility.

How do I set it up?

You can call this action via adding a call to this job in a GitHub Actions workflow. A minimal example that runs this on commits to main is:

---
name: Docs 📚

on:
  push:
    branches:
      - main

jobs:
  docs:
    name: Pkgdown Docs 📚
    uses: phuse-org/devops-toolkit/.github/workflows/pkgdown.yml@main

The deets

If you have built docs locally in the past, you are probably aware that your git repo will balloon in size, as it stores a copy of each piece version of every plot and image you have used in your documentation. This gh-action will help you avoid that, by placing the versioned documentation into an orphan branch. Helping to keep your docs (a built artefact) seperate from your source code.