diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..ca79ca5 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 8818468..aefa01d 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -4,27 +4,30 @@ on: push: branches: [main, master] pull_request: + types: [opened, reopened, synchronize, labeled] release: types: [published] workflow_dispatch: name: pkgdown.yaml -permissions: read-all - jobs: pkgdown: + # For PRs, only run when the PR has the build-website label. + if: >- + github.event_name != 'pull_request' || + contains(github.event.pull_request.labels.*.name, 'build-website') runs-on: ubuntu-latest # Only restrict concurrency for non-PR jobs concurrency: - group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} + group: pkgdown-${{ github.event_name == 'pull_request' && github.event.pull_request.number || 'production' }} cancel-in-progress: true env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} permissions: contents: write steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: r-lib/actions/setup-pandoc@v2 @@ -39,15 +42,35 @@ jobs: needs: website - name: Build site - run: >- - pkgdown::build_site_github_pages(clean = FALSE, new_process = TRUE, - install = FALSE) + id: pkgdown + run: | + pkgdown::build_site_github_pages(clean = FALSE, new_process = TRUE, install = FALSE) shell: Rscript {0} - - name: Deploy to GitHub pages 🚀 + - name: Get pkgdown destination + if: github.event_name == 'pull_request' + id: pkgdown-dest + run: | + echo "folder=$(Rscript -e 'cat(fs::path_rel(pkgdown::as_pkgdown(".", override = list(destination = "docs"))$dst_path))')" >> "$GITHUB_OUTPUT" + + - name: Deploy PR preview + # Forks cannot deploy the site + if: > + github.event_name == 'pull_request' && + github.event.pull_request.head.repo.full_name == github.repository + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: ${{ steps.pkgdown-dest.outputs.folder }} + target-folder: pr/${{ github.event.pull_request.number }} + clean: true + force: false + + - name: Deploy site if: github.event_name != 'pull_request' - uses: JamesIves/github-pages-deploy-action@v4.5.0 + uses: JamesIves/github-pages-deploy-action@v4 with: branch: gh-pages folder: docs - clean: true + clean: false + force: false diff --git a/vignettes/Quirks.qmd b/vignettes/Quirks.qmd index d5b7391..a7b4eb1 100644 --- a/vignettes/Quirks.qmd +++ b/vignettes/Quirks.qmd @@ -28,11 +28,11 @@ template: My_cool_html ``` -I left the functionality in so that the website wouldn't fail silently and eat your input, but I hazard that you won't want to put anything before the logo. If you want to put things in `before_title` you should copy my `navbar.HTML` into your package's pkgdown configuration and edit it, putting HTML where it says `{{#includes}}{{{before_navbar}}}{{/includes}}`. +I left the functionality in so that the website wouldn't fail silently and eat your input, but I hazard that you won't want to put anything before the logo. If you want to put things in `before_title` you should copy my `navbar.HTML` into your package's `pkgdown` configuration and edit it, putting HTML where it says `{{#includes}}{{{before_navbar}}}{{/includes}}`. ## Logs Say Favicons Missing -Due to how pkgdown and this template package work, pkgdown will complain about missing favicons initially, but will copy them over soon after. They will appear in the built site properly, so you can safely ignore this error. Unfortunately, I don't see any clean way of suppressing this error. +Due to how `pkgdown` and this template package work, `pkgdown` will complain about missing favicons initially, but will copy them over soon after. They will appear in the built site properly, so you can safely ignore this error. Unfortunately, I don't see any clean way of suppressing this error. ``` ── Sitrep ────────────────────────────────────────────────────────────────────── diff --git a/vignettes/Setup.qmd b/vignettes/Setup.qmd index ad2d9c5..13e363e 100644 --- a/vignettes/Setup.qmd +++ b/vignettes/Setup.qmd @@ -18,18 +18,16 @@ If you haven't started a `pkgdown` site yet, initialize it. usethis::use_pkgdown() ``` -In `./_pkgdown.yml` add the contributed package: +In `_pkgdown.yml` add the template package: ```yaml template: package: pkgdownconfig ``` -Optional but highly recommended is to set development mode to auto and to build the site in root, like so: +Optional but highly recommended is to set [development mode](https://pkgdown.r-lib.org/reference/build_site.html#setting-development-mode) to auto. This will build a dev version of the site at `/dev` (see [`loo`](https://mc-stan.org/loo/dev/) for example). Whether `pkgdown` treats a build as a development or release site is controlled by the version in DESCRIPTION (see pkgdown docs linked above). ```yaml -destination: "." - development: mode: auto ``` @@ -40,11 +38,10 @@ Point to this repository in `DESCRIPTION` to download the theme automatically. Config/Needs/website: stan-dev/pkgdown-config ``` -Optionally, you should be able to pin a specific version of the template with a tag or commit: +Optionally, you can pin a specific version of the template with a tag or commit, but this isn't reocmmended. ```yaml Config/Needs/website: stan-dev/pkgdown-config@v1.0.1 - Config/Needs/website: stan-dev/pkgdown-config@COMMITHASH ``` @@ -55,7 +52,7 @@ pak::pak("stan-dev/pkgdown-config") pkgdown::build_site() ``` -If you're getting an error about dependency resolution when using a GitHub Action to automatically build your pkgdown site, remove the `Config/Needs/website:` line from DESCRIPTION and add use the R dependencies step like [here]("https://mc-stan.org/pkgdown-config/articles/GitHub Action"): +If you're getting an error about dependency resolution when using a GitHub Action (GHA) to automatically build your pkgdown site, remove the `Config/Needs/website:` line from DESCRIPTION and add the pacakge to this GHA step: ```yaml - uses: r-lib/actions/setup-r-dependencies@v2 @@ -63,43 +60,12 @@ If you're getting an error about dependency resolution when using a GitHub Actio extra-packages: any::pkgdown, local::., stan-dev/pkgdown-config ``` -By default, the theme has a navbar item which has other Stan R packages--this is not smart and won't automatically drop the package you're using the theme in. If you don't want this, you should override that list in `_pkgdown.yml`. This example is taken from `loo`'s setup - -```yaml -navbar: - title: "loo" - - structure: - left: [home, vignettes, functions, news, pkgs, stan] - right: [search, bluesky, forum, github, lightswitch] - - components: - pkgs: - text: Other Packages - menu: - - text: bayesplot - href: https://mc-stan.org/bayesplot - - text: cmdstanr - href: https://mc-stan.org/cmdstanr - - text: posterior - href: https://mc-stan.org/posterior - - text: projpred - href: https://mc-stan.org/projpred - - text: rstan - href: https://mc-stan.org/rstan - - text: rstanarm - href: https://mc-stan.org/rstanarm - - text: rstantools - href: https://mc-stan.org/rstantools - - text: shinystan - href: https://mc-stan.org/shinystan -``` -## Example (`shinystan`) +## Example -Put together, here's what a reasonable YAML looks like (truncated, taken from `shinystan`): +Put together, here's what a typical YAML might look like: ```yaml -url: https://mc-stan.org/shinystan +url: https://mc-stan.org/PKGNAME destination: "." @@ -109,44 +75,30 @@ development: template: package: pkgdownconfig -navbar: - title: "shinystan" - - structure: - left: [home, vignettes, functions, news, pkgs, stan] - right: [search, bluesky, forum, github, lightswitch] - - components: - pkgs: - text: Other Packages - menu: - - text: bayesplot - href: https://mc-stan.org/bayesplot - - text: cmdstanr - href: https://mc-stan.org/cmdstanr - - text: "loo" - href: https://mc-stan.org/loo - - text: posterior - href: https://mc-stan.org/posterior - - text: projpred - href: https://mc-stan.org/projpred - - text: rstan - href: https://mc-stan.org/rstan - - text: rstanarm - href: https://mc-stan.org/rstanarm - - text: rstantools - href: https://mc-stan.org/rstantools - -# now you can add articles, references, etc. +articles: + - title: "Article 1" + ... + +reference: + - title: "Function Group 1" + ... ``` +## GHA + +You can use the default GHA, or you can copy [this package's GHA](https://github.com/stan-dev/pkgdown-config/blob/main/.github/workflows/pkgdown.yaml). This GHA deploys `pkgdown` sites on (non-fork[^1]) PRs to unique URLs (`/prs/$PR-NUMBER`). This means that PRs would have preview sites, `/dev` would track `main`, and the main site would track releases. + +You could also configure the `pkgdown` GHA to only run when [vignettes are modified](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events), or only have the `workflow_dispatch` trigger so that you can build PR's `pkgdown` sites as needed. + +[^1]:PRs from forks typically get a read-only `GITHUB_TOKEN` for security, so they wouldn't be able to deploy the site. + ## Common Issues -If for some reason the favicons don't get copied over, check if you are defining favicons in `pkgdown/favicons`. In most cases you can delete everything in that folder--just delete the logo and favicons if you are worried. The template will hook in the correct favicon and logo. If its not working, download [logo.svg](https://github.com/stan-dev/logos/blob/master/logo.svg) to `/man/figures/logo.svg` and run `pkgdown::build_favicons()` once to build the favicons. +If for some reason the new favicons don't get copied over, check if you are defining favicons in `pkgdown/favicons`. In most cases you can delete everything in that folder--just delete the logo and favicons if you are worried. The template will hook in the correct favicon and logo. If its not working, download [logo.svg](https://github.com/stan-dev/logos/blob/master/logo.svg) to `/man/figures/logo.svg` and run `pkgdown::build_favicons()` once to build the favicons. -If you want the hex in your README (or if it isn't working), make sure to edit the `README.MD` or however you generate it. You can take a look at this package's to get an idea of what you need to do (repeated below): +If you want the hex in your README (or if it isn't working), make sure to edit the `README.md` or however you generate it. You can take a look at this package's to get an idea of what you need to do (repeated below): ```md # pkgdownConfig pkgdownConfig website