| Title: | Helpers to Develop Packages with GitHub Actions |
|---|---|
| Description: | Helpers for package maintenance, documentation rendering and GitHub Actions workflows. The package is primarily intended for personal use, but you are welcome to use it at your own risk. |
| Authors: | Diego Hernangómez [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-8457-4658>) |
| Maintainer: | Diego Hernangómez <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0.9150 |
| Built: | 2026-10-17 13:54:23 UTC |
| Source: | https://github.com/dieghernan/pkgdev |
.gitignore file to a packageAdds a global .gitignore file to the package. The file is based on the
default .gitignore provided by GitHub.
add_global_gitgnore(pkg = ".")add_global_gitgnore(pkg = ".")
pkg |
Path to the package root directory. |
NULL, invisibly, after updating .gitignore files.
usethis::use_git_ignore() adds entries to .gitignore.
usethis::git_vaccinate() adds global Git ignore rules.
Package maintenance helpers:
update_docs()
## Not run: add_global_gitgnore() ## End(Not run)## Not run: add_global_gitgnore() ## End(Not run)
build_qmd() is a wrapper around quarto::quarto_render() that first
installs a temporary copy of the package, then renders each Quarto file in a
clean R session. build_readme_qmd() locates your README.qmd and builds
it into README.md.
build_qmd(files, path = ".", ..., quiet = TRUE) build_readme_qmd(path = ".", quiet = TRUE, ...)build_qmd(files, path = ".", ..., quiet = TRUE) build_readme_qmd(path = ".", quiet = TRUE, ...)
files |
Quarto files to be rendered. |
path |
Path to the top-level directory of the source package. |
... |
Additional arguments passed to |
quiet |
If |
A logical value, TRUE, invisibly, after rendering
the Quarto files.
update_docs() runs the broader package maintenance workflow.
devtools::build_readme() builds README files from R Markdown.
Documentation rendering helpers:
precompute_vignette()
Checks generated Rd file titles for sentence case and trailing periods.
check_rd_titles(pkg = ".")check_rd_titles(pkg = ".")
pkg |
Path to the package root directory. |
A data frame with one row per Rd file and
columns for the source path, title, sentence-case title, final character
and sentence-case check. Returns NULL if no Rd files
are found.
update_docs() runs this check after roxygenizing the package.
## Not run: check_rd_titles() ## End(Not run)## Not run: check_rd_titles() ## End(Not run)
The GitHub Actions workflow runs R CMD check on your package.
It uses a wide range of platforms, which can be reduced by commenting out or
deleting platforms in the matrix configuration.
gha_check_full(pkg = ".", overwrite = TRUE, cron_expr = "30 08 1 * *")gha_check_full(pkg = ".", overwrite = TRUE, cron_expr = "30 08 1 * *")
pkg |
Path to the package root directory. |
overwrite |
Whether to overwrite an existing workflow file. |
cron_expr |
A valid cron expression. Defaults to 08:30 UTC on the first day of the month. See Details. |
Use crontab.guru to check and create your own cron expression.
NULL, invisibly, after writing a GitHub Actions
workflow to <pkg>/.github/workflows.
Examples from r-lib/actions.
usethis::use_github_action() creates GitHub Actions workflows.
GitHub Actions workflow helpers:
gha_pkgdown_branch(),
gha_update_docs()
## Not run: gha_check_full(cron_expr = "57 16 12 * *") ## End(Not run)## Not run: gha_check_full(cron_expr = "57 16 12 * *") ## End(Not run)
The GitHub Actions workflow deploys a pkgdown site for your
package to the gh-pages branch.
gha_pkgdown_branch( pkg = ".", overwrite = TRUE, platform = "macOS", version = "latest" )gha_pkgdown_branch( pkg = ".", overwrite = TRUE, platform = "macOS", version = "latest" )
pkg |
Path to the package root directory. |
overwrite |
Whether to overwrite an existing workflow file. |
platform |
Runner operating system to use for deploying the site. See Details. |
version |
Runner image version. See Details. |
Check https://github.com/actions/runner-images to see the available options.
NULL, invisibly, after writing a GitHub Actions
workflow to <pkg>/.github/workflows.
Examples from r-lib/actions.
pkgdown::build_site() builds the package website locally.
GitHub Actions workflow helpers:
gha_check_full(),
gha_update_docs()
## Not run: # With Ubuntu 20.04. gha_pkgdown_branch(platform = "ubuntu", version = "20.04") ## End(Not run)## Not run: # With Ubuntu 20.04. gha_pkgdown_branch(platform = "ubuntu", version = "20.04") ## End(Not run)
The GitHub Actions workflow documents your package (see update_docs()),
checks it and deploys its pkgdown site to the gh-pages branch.
gha_update_docs( pkg = ".", overwrite = TRUE, platform = "macOS", version = "latest" )gha_update_docs( pkg = ".", overwrite = TRUE, platform = "macOS", version = "latest" )
pkg |
Path to the package root directory. |
overwrite |
Whether to overwrite an existing workflow file. |
platform |
Runner operating system to use for deploying the site. See Details. |
version |
Runner image version. See Details. |
Check https://github.com/actions/runner-images to see the available options.
NULL, invisibly, after writing a GitHub Actions
workflow to <pkg>/.github/workflows.
Examples from r-lib/actions.
update_docs() documents and checks your package.
GitHub Actions workflow helpers:
gha_check_full(),
gha_pkgdown_branch()
## Not run: # With Ubuntu 20.04. gha_update_docs(platform = "ubuntu", version = "20.04") ## End(Not run)## Not run: # With Ubuntu 20.04. gha_update_docs(platform = "ubuntu", version = "20.04") ## End(Not run)
Precompute vignettes following the CRAN approach described at https://ropensci.org/blog/2019/12/08/precompute-vignettes/.
precompute_vignette( source, pkg = ".", figure_ext = ".png", create_r_file = FALSE ) precompute_vignette_all(dir = "vignettes", pkg = ".", ...)precompute_vignette( source, pkg = ".", figure_ext = ".png", create_r_file = FALSE ) precompute_vignette_all(dir = "vignettes", pkg = ".", ...)
source |
Name of the |
pkg |
Path to the package root directory. |
figure_ext |
File extension for figures plotted in the vignette. See Details. |
create_r_file |
Whether to create an additional R script with the code from the vignette. |
dir |
Path to the directory where the |
... |
Additional arguments passed to |
This function reads vignette source files from the package's vignettes
directory and moves plots from the package root to that directory.
precompute_vignette() processes the files named in source.
precompute_vignette_all() finds and processes every .Rmd.orig and
.qmd.orig file in dir.
In your .Rmd.orig or .qmd.orig file, set the following chunk option when
producing plots:
knitr::opts_chunk$set( ..., fig.path = "./", ..., )
NULL, invisibly, after precomputing the vignettes.
Based on https://ropensci.org/blog/2019/12/08/precompute-vignettes/.
update_docs() runs the broader package maintenance workflow.
Documentation rendering helpers:
build_qmd()
## Not run: precompute_vignette(source = "precompute.Rmd.orig") ## End(Not run)## Not run: precompute_vignette(source = "precompute.Rmd.orig") ## End(Not run)
Performs routine package maintenance:
Clean DESCRIPTION with usethis::use_tidy_description().
Compress data in the "./data" and "./R" paths using
tools::resaveRdaFiles().
Style code with styler::style_pkg().
Check URLs with urlchecker::url_check().
Roxygenize with roxygen2::roxygenise().
Precompute vignettes with precompute_vignette_all() if present.
Rebuild README.qmd, README.Rmd or pkgdown index files, if
present.
Optimize images with resmush::resmush_dir().
Write codemeta.json with codemetar::write_codemeta().
Write CITATION.cff with cffr::cff_write().
Write a project-level Codex configuration file.
update_docs( pkg = ".", url_update = TRUE, create_codemeta = TRUE, create_cff = TRUE, build_readme = TRUE, verbose = TRUE, precompute = TRUE, opt_imgs = TRUE, opt_dir = c("man/figures", "vignettes"), opt_ext = "png$|jpg$", opt_overwrite = TRUE, add_contributors = TRUE, ... )update_docs( pkg = ".", url_update = TRUE, create_codemeta = TRUE, create_cff = TRUE, build_readme = TRUE, verbose = TRUE, precompute = TRUE, opt_imgs = TRUE, opt_dir = c("man/figures", "vignettes"), opt_ext = "png$|jpg$", opt_overwrite = TRUE, add_contributors = TRUE, ... )
pkg |
Path to the package root directory. |
url_update |
A logical value. Should URLs be updated with
|
create_codemeta |
A logical value. Should |
create_cff |
A logical value. Should |
build_readme |
A logical value. Should |
verbose |
A logical value. Should progress messages be displayed in the console? |
precompute |
A logical value. Should vignettes be detected and
precomputed? See also |
opt_imgs |
A logical value. Should images be optimized with
|
opt_dir, opt_ext, opt_overwrite
|
Options passed to the |
add_contributors |
Deprecated. |
... |
Additional arguments passed to downstream functions. |
This function checks URLs, regenerates roxygen2 documentation and rebuilds
the README. It also applies the tidyverse style to DESCRIPTION
and package code and writes package metadata to codemeta.json.
NULL, invisibly, after updating the package.
Emits progress messages when verbose = TRUE.
build_qmd() builds Quarto files.
build_readme_qmd() builds README.md from README.qmd.
check_rd_titles() checks generated Rd titles.
gha_update_docs() automates this workflow with GitHub Actions.
precompute_vignette_all() precomputes all vignette source files.
devtools::build_readme() builds README.Rmd files.
Package maintenance helpers:
add_global_gitgnore()
## Not run: update_docs() ## End(Not run)## Not run: update_docs() ## End(Not run)