develop vignette to show how to set up pkgdown

[k-doering-NOAA]

The level of detail in the readme may not yet be sufficient for people new to github actions. We may want to create a vignette that shows step-by-step how to set up the workflows and describe potential issues/decision points.

[k-doering-NOAA]

Maybe we could add to the FIT pages instead of making a vignette; for example, we can add on to this pkgdown setup instructions to include instructions on setting up the automated workflow, for example. We could then link to it in the readme.

[Bai-Li-NOAA]

Good idea. Below are two links that I found very helpful when setting up some of the reusable workflows.

• Add nonstandard dependencies to DESCRIPTION file: https://r-pkgs.org/description.html#nonstandard-dependencies
• Create an empty gh-pages branch before setting up GitHub Actions to deploy a pkgdown site: https://orchid00.github.io/actions_sandbox/websites-using-pkgdown-bookdown-and-blogdown.html

[iantaylor-NOAA]

+1 for this issue.
I was just suggesting the use of {ghactions4r} and realized that I didn't know the right sequence of steps related to changing the settings to deploy pages from a branch (and you can't choose the branch before it exists).

[k-doering-NOAA]

Thanks @iantaylor-NOAA I was just thinking about this issue today, that in particular setting up pkgdown or bookdown is not documented here but should be.

[k-doering-NOAA]

One thing that could help would be using the usethis ui_* functions to provide more info when the user sets up the action.

[k-doering-NOAA]

I just went through the process of setting up pkgdown on SSMSE by following these instructions: https://noaa-fisheries-integrated-toolbox.github.io/resources/noaa%20resources/NOAA-pkgdown/

It was pretty straightforward, except I also had a bookdown user manual that needed to live in the docs/ folder. I ended up setting up a custom workflow so I could render the pkgdown followed by bookdown, then deploy both. If I didn't also have the bookdown, there would have not been any issues.

I think the takeaway here is to tell people to set up their pkgdown locally, check that it works, then tell them to add the github action and point it to gh pages. All of the steps are listed in the FIT blog post so I think linking it in the vignette/use_pkgdown function reference should be sufficient.