use_doc_and_style_r.RdStyle your R package components automatically by running devtools::document(), styler::style_pkg() or air, and usethis::use_tidy_description().
use_doc_and_style_r(
workflow_name = "call-doc-and-style-r.yml",
use_rm_dollar_sign = FALSE,
how_to_commit = c("pull_request", "directly"),
build_trigger = "push_to_main",
use_air = FALSE,
use_pat = FALSE,
pat_name = "PAT",
tag_ghactions4r = NULL
)What to name the github action workflow locally. Must
have the file extension .yml
in addition to devtools::document and styler::style_pkg, should ghactions4r::rm_dollar_sign be run? Defaults to FALSE.
Where should changes made to style and documentation be committed? Options are 1) in a pull request to the branch ("pull_request") where the workflow started; or 2) directly to the branch ("directly") where the workflow started.
Select the event that triggers the workflow. Options are:
push_to_mainRun on pushing commits to main (default)
pull_requestRun when a pull request is opened, reopened, or updated
pr_commentRun when a comment containing the command \doc-and-style is made on a pull request by people with write permissions on the repository
manuallyRun manually with the workflow_dispatch trigger
weeklyRun on the default branch (usually main) once a week
Multiple build triggers are allowed; specify them as a vector. Note that invalid build triggers will be silently removed as long as one build trigger is specified correctly.
Use air instead of styler to style files? Defaults to FALSE.
Should a personal access token (PAT) stored as a GitHub secret be used? This is only necessary if you want the pull request generated by the doc and style workflow to be able to start other GitHub action runs.
Name of the personal access token (PAT), as stored in secrets.
Only used if use_pat = TRUE. After
generating the personal access token,
See how to add it as a secret.
Tag of ghactions4r workflow to pin to for the reusable workflow. This ensures compatibility with a specific version of ghactions4r functions. The tradeoff is that fixes will not happen automatically; instead, the user will have to update the pinned version of the caller workflow used. See the options by looking at the ghactions4r tags. Another option is to pin to commit hashes, but the user will need to do this by manually editing the caller workflow after creation. See github documentation on security to understand how this is more secure. Again, the tradeoff is that the workflow will not be automatically updated.
The pull request created from this workflow can trigger GitHub Action runs by using a personal access token (instead of the standard GITHUB_TOKEN) to provide the right permissions. The PAT is first generated on a user account, then added to the repository or organization as a secret. Using a PAT can cause recursive runs, so should be used with caution. See github documentation on triggering a workflow from a workflow for more information.
If using the PR_comment build trigger, note that the command to run the workflow
# set up running the doc and style workflow on each push to main, opening a
# pull request to main when changes are found.
if (FALSE) { # \dontrun{
use_doc_and_style_r()
} # }
# the same as
if (FALSE) { # \dontrun{
use_doc_and_style_r(
how_to_commit = "pull_request",
build_trigger = "push_to_main"
)
} # }
# Set up running doc and style on each pull request, committing directly to
# the pull request branch
if (FALSE) { # \dontrun{
use_doc_and_style_r(
how_to_commit = "directly",
build_trigger = "pull_request"
)
} # }
# Set up the workflow to use a personal access token (PAT)
if (FALSE) { # \dontrun{
use_doc_and_style_r(use_pat = TRUE, pat_name = "PAT")
} # }
# set up to run doc and style on a pull request, where an owner or member of
# the repository adds a comment on the pull request with the command \doc-and-style
if (FALSE) { # \dontrun{
use_doc_and_style_r(build_trigger = "pr_comment")
} # }