| 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-07-15 20:45:44 UTC |
| Source: | https://github.com/dieghernan/pkgdev |
.gitignore to 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 a (subdirectory of an) R package. |
Invisibly returns NULL after writing a global .gitignore file.
update_docs() runs package maintenance tasks that call
add_global_gitgnore().
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 .Rmd in a
clean R session. build_readme_qmd() locates your README.qmd and builds
it into a 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 |
TRUE, invisibly.
build_readme_qmd() builds README.qmd files.
precompute_vignette() precomputes vignettes.
devtools::build_readme() builds README files from R Markdown.
Documentation renderers:
precompute_vignette()
Inspect generated Rd file titles for sentence case and trailing periods.
check_rd_titles(pkg = ".")check_rd_titles(pkg = ".")
pkg |
Path to a (subdirectory of an) R package. |
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.
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 a (subdirectory of an) R package. |
overwrite |
Overwrite the action if it was already present. |
cron_expr |
Valid cron expression. By default, the first day of the month at 08:30 AM. See Details. |
Use crontab.guru to check and create your own cron tag.
Invisibly returns NULL after writing a GitHub Actions workflow to
<pkg>/.github/workflows.
Examples from r-lib/actions.
gha_pkgdown_branch() creates a pkgdown deployment action.
gha_update_docs() creates a documentation and deployment action.
usethis::use_github_action() creates GitHub Actions workflows.
GitHub Actions 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 on 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 a (subdirectory of an) R package. |
overwrite |
Overwrite the action if it was already present. |
platform |
Platform to use for deploying the package. See Details. |
version |
Version of the platform. See Details. |
Check https://github.com/actions/runner-images to see the available options.
Invisibly returns NULL after writing a GitHub Actions workflow to
<pkg>/.github/workflows.
Examples from r-lib/actions.
gha_check_full() creates a full package check action.
gha_update_docs() creates a documentation and deployment action.
GitHub Actions 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 the package on a 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 a (subdirectory of an) R package. |
overwrite |
Overwrite the action if it was already present. |
platform |
Platform to use for deploying the package. See Details. |
version |
Version of the platform. See Details. |
Check https://github.com/actions/runner-images to see the available options.
Invisibly returns NULL after writing a GitHub Actions workflow to
.github/workflows.
Examples from r-lib/actions.
update_docs() documents and checks your package.
gha_check_full() creates a full package check action.
gha_pkgdown_branch() creates a pkgdown deployment action.
GitHub Actions 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 using the CRAN approach, based on 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 a (subdirectory of an) R package. |
figure_ext |
Extension of the figures plotted in the vignette. See Details. |
create_r_file |
Whether to create an additional R script with the code of the vignette. |
dir |
Path to the directory where the |
... |
Parameters passed to |
This function searches for the desired precomputed vignette in the
"./vignettes/" directory and for plots in the root "./" directory.
In your .Rmd.orig file, make sure you have set at least the following
lines if you are producing plots:
knitr::opts_chunk$set( ..., fig.path = "./", ..., )
Invisibly returns NULL after writing a precomputed vignette.
Based on https://ropensci.org/blog/2019/12/08/precompute-vignettes/.
build_qmd() builds Quarto files.
build_readme_qmd() builds README.qmd files.
Documentation renderers:
build_qmd()
## Not run: precompute_vignette(source = "precompute.Rmd.orig") ## End(Not run)## Not run: precompute_vignette(source = "precompute.Rmd.orig") ## End(Not run)
Run routine checks on the package:
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, if present (see https://ropensci.org/blog/2019/12/08/precompute-vignettes/).
Rebuild README.Rmd, if present, with devtools::build_readme().
Optimize images with resmush::resmush_dir().
Write codemeta.json with codemetar::write_codemeta().
Write CITATION.cff with cffr::cff_write().
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 a (subdirectory of an) R package. |
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 informative messages be displayed on 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 updates and cleans the package using a mix of best practices,
such as checking URLs, roxygenizing and rebuilding the README. It also
applies discretionary practices such as the tidyverse approach for the
DESCRIPTION file, overall code style and codemeta.json.
Invisibly returns NULL. When verbose = TRUE, it emits progress
messages.
add_global_gitgnore() updates package ignore files.
build_qmd() builds Quarto files.
check_rd_titles() checks generated Rd titles.
precompute_vignette() precomputes vignettes.
usethis::use_tidy_description() cleans DESCRIPTION.
styler::style_pkg() styles package code.
urlchecker::url_check() checks URLs.
roxygen2::roxygenise() updates documentation.
devtools::build_readme() builds README.Rmd.
codemetar::write_codemeta() writes codemeta.json.
tools::resaveRdaFiles() compresses data files.
Package maintenance helpers:
add_global_gitgnore()
## Not run: update_docs() ## End(Not run)## Not run: update_docs() ## End(Not run)