allow manual deploy-with-clean pkgdown deployment

[cjyetman]

This seems like a lot, but see here why it is difficult to safely achieve.

I discovered that when JamesIves/github-pages-deploy-action runs with clean: false (which is default in the recommended r-lib pkgdown action), old pages on the pkgdown site that are no longer needed are not removed, e.g. if there was a vignette/article but it has since been removed. This creates a situation where out-of-date, potentially misleading, information may still be accessible at its old URL even if it is not shown in the menu. As a specific example, I found that the pactaverse pkgdown site was pointing to the TDM article on the pacta.portfolio.allocate pkgdown site and it was still accessible, even though the vignette had been removed and it was not directly accessible from the Articles menu on the pacta.portfolio.allocate pkgdown site.

The clean: false option was added to r-lib's example pkgdown.yml to facilitate pkgdown setups that build separate prod and dev pkgdown sites (like our r2dii/P4B pkgs). This makes sense, because if you're only building the sub dev version of the site, you don't want to wipe out the prod top-level site while you're at it. But it does prevent you from clearing out old site files that should no longer be there. With the r2dii packages, the "release" version of the pkgdown website shows the menu text in black instead of white, and it appears it cannot be fixed until some of those old files are wiped out, which cannot be achieved without using the clean: true option.

A tedious solution to this is to temporarily change clean: false to clean: true in the pkgdown.yml workflow, merge it so it will run on main, let the pkgdwon site build and deploy (with the clean: true option in place), and then presumably change it back (?). However, this would affect only the "dev" version of pkgdown website, if/until a new release was made.

A somewhat more complicated solution, but one that can remain in place is to allow a manual triggering of the pkdown site build and deploy with an optional clean: true specification. This way, if you notice that a clean needs to be done, you can trigger it manually and specify clean: true, but otherwise (on merge or manual trigger with default options) the build/deploy will run as normal. That's what I've done here. Additionally, and importantly, when triggering the pkgdown workflow manually, you can specify a branch or a tag (release) to run it on.

In order to make this work for our current problem (updating the release version of the pkgdown site with the new pkgdown config), we will need to make a new branch based on the v0.4.0 tag, commit the new pkgdown config to to that new branch, manually trigger the pkgdown action on that new branch with the clean: true option, and then we can delete that new branch (without ever having to make a PR much less merging it).