[Feature]: Add a workflow to check that a package down site can be built

[kellijohnson-NOAA]

Is your feature request related to a problem? Please describe.

I sometimes make changes to the code, like removing a function, and then forget that there may be changes needed to the package down site like removing the function from a list of grouped functions.

Describe the solution you would like.

Is there a way to add a workflow that just checks if a package down site builds successfully? That way, the new workflow could be used in tests run when checking Pull Requests because we do not actually want the built site to be deployed.

Describe alternatives you have considered

• Write a note to have users check the package down site manually if one exists
• Modify the current workflow that builds the site to see if it is being ran on a pull request and only check if it can build
• Modify the current workflow to accept an argument if you actually want the site to be built

Additional context

See this issue in FIMS, where I did not make the necessary changes to the package down site and @Bai-Li-NOAA caught my error when reviewing a pull request.

[k-doering-NOAA]

Thanks @kellijohnson-NOAA! I think this would be possible by using pkgdown::build_site() (as shown in the pkgdown documentation in the github actions and then saving the output as an artifact.

Here is the start for the reusable workflow (not tested yet)

# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
on:
  workflow_call:

name: build-pkgdown

jobs:
  pkgdown:
    runs-on: ubuntu-latest
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-pandoc@v2

      - 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 pkgdown
        run: |
          Rscript -e 'pkgdown::build_site()'
     
      #save pkgdown output
      - uses: actions/upload-artifact@v4
        with:
          name: pkgdown-site
          path: docs/
     

[Bai-Li-NOAA]

Thanks, Kathryn, this looks great. I'd be happy to reuse the workflow and test it with FIMS on pull request if you need a tester.

[kellijohnson-NOAA]

Thanks @k-doering-NOAA for working on this so quickly. I am curious @Bai-Li-NOAA when I broke the FIMS site, how did you know? Did you have to look at something manually? Or, were there messages returned from pkgdown::build_site()? I see that pkgdown uses cli::cli*() message for successful builds, e.g., cli::cli_rule("Finished building pkgdown site for package {.pkg {pkg$package}}") but I do not know if there are sufficient warning messages?

[Bai-Li-NOAA]

@kellijohnson-NOAA, I often encounter similar issues when updating R functions in other projects, so I suspected there might be problems with building the pkgdown site after noticing that a few R functions were removed from the FIMS repo. And yes, I ran pkgdown::build_site() locally and got the error messages.

[k-doering-NOAA]

@Bai-Li-NOAA, it would be great to have you test! I'll let you know once I put the reusable version on a branch. Good to know that build_site() errors.