,
Hauke Sonnenberg [aut] ,
FAKIN [fnd],
Kompetenzzentrum Wasser Berlin gGmbH (KWB) [cph]| Title: | R package for standardised development at KWB |
|---|---|
| Description: | Helper functions for automating R package development at KWB to a predefined style. |
| Authors: | Michael Rustler [aut, cre] ,
Hauke Sonnenberg [aut] ,
FAKIN [fnd],
Kompetenzzentrum Wasser Berlin gGmbH (KWB) [cph] |
| Maintainer: | Michael Rustler <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.3 |
| Built: | 2024-11-14 04:29:50 UTC |
| Source: | https://github.com/KWB-R/kwb.pkgbuild |
Copy files from Vignettes Dir to Deploy idir
copy_files_from_vignettes_dir_to_deploy_dir( source_dir = ".", deploy_dir = "docs", pattern = "\\.json$", overwrite = TRUE )copy_files_from_vignettes_dir_to_deploy_dir( source_dir = ".", deploy_dir = "docs", pattern = "\\.json$", overwrite = TRUE )
source_dir |
default: "." |
deploy_dir |
default: "docs |
pattern |
file pattern to export (default: "\.json$") |
overwrite |
should existing files be overwritten (default: TRUE) |
files matching pattern copied to deploy_dir
Create Empty Branch From Github
create_empty_branch( repo = NULL, branch = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )create_empty_branch( repo = NULL, branch = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )
repo |
name of existing Github repository (default: NULL) |
branch |
name of branch to be created (default: NULL) |
org |
repo owner (default: "KWB-R") |
set_githubuser |
should the Github user be set before executing the branch creation (default: TRUE). In this case set_github_user() is run |
git_exe |
path to GIT executable (default: kwb.pkgbuild:::path_to_git()), only required on "windows". On all other platforms it is assumed that "git" is sufficient! |
dest_dir |
directory where the the repo should be checked out (default: tempdir()) |
execute |
should a batch file be run? |
dbg |
print debug messages (default: TRUE) |
... |
additional arguments passed to set_github_user |
create empty branch (defined in 'branch') and push to org/repo on Github
Create Empty gh-pages branch
create_empty_branch_ghpages( repo = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )create_empty_branch_ghpages( repo = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )
repo |
name of existing Github repository (default: NULL) |
org |
repo owner (default: "KWB-R") |
set_githubuser |
should the Github user be set before executing the branch creation (default: TRUE). In this case set_github_user() is run |
git_exe |
path to GIT executable (default: kwb.pkgbuild:::path_to_git()), only required on "windows". On all other platforms it is assumed that "git" is sufficient! |
dest_dir |
directory where the the repo should be checked out (default: tempdir()) |
execute |
should a batch file be run? |
dbg |
print debug messages (default: TRUE) |
... |
additional arguments passed to set_github_user |
create and push an empty gh-pages branch to org/repo
Create Package Directory
create_pkg_dir(pkg_dir)create_pkg_dir(pkg_dir)
pkg_dir |
path to package directory to be created, including the pkgname as last folder |
creates directory for package if not existing
## not a valid pkg folder ## Not run: pkg_dir <- file.path(tempdir(), "pkgname/pkgname") create_pkg_dir(pkg_dir) ## End(Not run) ## valid pkg folder pkg_dir <- file.path(tempdir(), "pkgname") create_pkg_dir(pkg_dir)## not a valid pkg folder ## Not run: pkg_dir <- file.path(tempdir(), "pkgname/pkgname") create_pkg_dir(pkg_dir) ## End(Not run) ## valid pkg folder pkg_dir <- file.path(tempdir(), "pkgname") create_pkg_dir(pkg_dir)
for details see pkgdown::deploy_site_github(), only parameter vignettes_file_pattern_to_copy added
deploy_site_github_with_extra_files( pkg = ".", vignettes_file_pattern_to_copy = "\\.json$", install = TRUE, tarball = Sys.getenv("PKG_TARBALL", ""), ssh_id = Sys.getenv("id_rsa", ""), commit_message = construct_commit_message(pkg), clean = FALSE, verbose = TRUE, host = "github.com", repo_slug = Sys.getenv("TRAVIS_REPO_SLUG", ""), ... )deploy_site_github_with_extra_files( pkg = ".", vignettes_file_pattern_to_copy = "\\.json$", install = TRUE, tarball = Sys.getenv("PKG_TARBALL", ""), ssh_id = Sys.getenv("id_rsa", ""), commit_message = construct_commit_message(pkg), clean = FALSE, verbose = TRUE, host = "github.com", repo_slug = Sys.getenv("TRAVIS_REPO_SLUG", ""), ... )
pkg |
"." |
vignettes_file_pattern_to_copy |
file patern for copying files from vignettes directory into deploy directory (default: "\.json$") |
install |
Optionally, opt-out of automatic installation. This is necessary if the package you're documenting is a dependency of pkgdown |
tarball |
tarball Sys.getenv("PKG_TARBALL", "") |
ssh_id |
ssh_id Sys.getenv("id_rsa", "") |
commit_message |
commit_message (default: construct_commit_message(pkg)) |
clean |
Clean all files from old site (default: FALSE) |
verbose |
Print verbose output (default: TRUE) |
host |
The GitHub host url (default: "github.com") |
repo_slug |
The 'user/repo' slug for the repository. |
... |
additional arguments passed to [deploy_to_branch_with_extra_files] |
deploy pkgdown site including additional files in "vignettes" source folder to "gh-pages"
Assumes that you're in a git clone of the project, and the package is already installed.
deploy_to_branch_with_extra_files( pkg = ".", vignettes_file_pattern_to_copy = "\\.json", commit_message = construct_commit_message(pkg), clean = FALSE, branch = "gh-pages", remote = "origin", github_pages = (branch == "gh-pages"), ... )deploy_to_branch_with_extra_files( pkg = ".", vignettes_file_pattern_to_copy = "\\.json", commit_message = construct_commit_message(pkg), clean = FALSE, branch = "gh-pages", remote = "origin", github_pages = (branch == "gh-pages"), ... )
pkg |
"." |
vignettes_file_pattern_to_copy |
file patern for copying files from vignettes directory into deploy directory (default: "\.json$") |
commit_message |
commit_message (default: construct_commit_message(pkg)) |
clean |
Clean all files from old site (default: FALSE) |
branch |
The git branch to deploy to |
remote |
The git remote to deploy to |
github_pages |
Is this a GitHub pages deploy. If 'TRUE', adds a 'CNAME' file for custom domain name support, and a '.nojekyll' file to suppress jekyll rendering. |
... |
Additional arguments passed to pkgdown::build_site() |
Helper Function: Get Package Name
get_pkgname(pkgname = NULL)get_pkgname(pkgname = NULL)
pkgname |
either package name or NULL. In this case the DESCRIPTION file in the current working directory is read and is package name ues (default: NULL) |
package name
Git Check Configuration
git_check_config(git_exe = path_to_git())git_check_config(git_exe = path_to_git())
git_exe |
path to git executable on Windows (default: path_to_git()) |
prints 'global' and 'local' Git configuration
## Not run: git_check_config() ## End(Not run)## Not run: git_check_config() ## End(Not run)
Git Setup User (Name and Email)
git_setup_user( github_username, github_email, scope = c("local", "global"), git_exe = path_to_git() )git_setup_user( github_username, github_email, scope = c("local", "global"), git_exe = path_to_git() )
github_username |
username should be your GitHub username |
github_email |
email should be identical to email you registered with at GitHub (e.g. your.name(at)kompetenz-wasser.de) |
scope |
scope (default: c("local", "global")) |
git_exe |
path to git executable on Windows (default: path_to_git()) |
runs "git" to setup the Git(Hub) user
<https://support.rstudio.com/hc/en-us/community/posts/115001143667-Author-Change-with-Git-in-RStudio>
## Not run: git_setup_user("mrustl", "[email protected]") ## End(Not run)## Not run: git_setup_user("mrustl", "[email protected]") ## End(Not run)
Helper function: read_description
read_description(file = "DESCRIPTION")read_description(file = "DESCRIPTION")
file |
path to DESCRIPTION file (default: DESCRIPTION) |
list with pkg "name", "title", "desc", "version"
Set Github User For GIT
set_github_user( git_username = "kwb.pkgbuild::use_autopkgdown()", git_fullname = "kwb.pkgbuild::use_autopkgdown()", git_email = "[email protected]", git_exe = path_to_git(), execute = FALSE, execute_dir = tempdir(), dbg = TRUE )set_github_user( git_username = "kwb.pkgbuild::use_autopkgdown()", git_fullname = "kwb.pkgbuild::use_autopkgdown()", git_email = "[email protected]", git_exe = path_to_git(), execute = FALSE, execute_dir = tempdir(), dbg = TRUE )
git_username |
Github username (default: "kwb.pkgbuild::use_autopkgdown()") |
git_fullname |
Github fullname (default: "kwb.pkgbuild::use_autopkgdown()") |
git_email |
(default: '[email protected]'), is then internally derived by calling whoami::fullname() and assuming that Github "kompetenz-wasser.de" used as email on Github |
git_exe |
path git git executable (only used on Windows as it is not installed in the local "environment"). On all other plattforms it is assumed that a call with "git" works |
execute |
should a batch file be run? |
execute_dir |
path to directory where batch script should be run in case that execute == TRUE (default: tempdir()) |
dbg |
print debug messages (default: TRUE) |
sets globally user.name and user.email in Git
automate pkgdown::build_site by running it on Travis and deploying to gh-pages branch
use_autopkgdown( repo = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )use_autopkgdown( repo = NULL, org = "KWB-R", set_githubuser = TRUE, git_exe = path_to_git(), dest_dir = tempdir(), execute = TRUE, dbg = TRUE, ... )
repo |
name of existing Github repository (default: NULL) |
org |
repo owner (default: "KWB-R") |
set_githubuser |
should the Github user be set before executing the branch creation (default: TRUE). In this case set_github_user() is run |
git_exe |
path to GIT executable (default: kwb.pkgbuild:::path_to_git()), only required on "windows". On all other platforms it is assumed that "git" is sufficient! |
dest_dir |
directory where the the repo should be checked out (default: tempdir()) |
execute |
should a batch file be run? |
dbg |
print debug messages (default: TRUE) |
... |
additional arguments passed to set_github_user |
workflow required for automating pkgdown::build_site() on Travis
Badge appveyor
use_badge_appveyor(repo = NULL, user = "KWB-R", domain = "github")use_badge_appveyor(repo = NULL, user = "KWB-R", domain = "github")
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
domain |
under which repository is hosted (default: "github") |
generates appveyor badge link
Badge codecov
use_badge_codecov(repo = NULL, user = "KWB-R", domain = "github")use_badge_codecov(repo = NULL, user = "KWB-R", domain = "github")
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
domain |
under which repository is hosted (default: "github") |
generates codecov badge link
Badge CRAN
use_badge_cran(pkgname = NULL)use_badge_cran(pkgname = NULL)
pkgname |
name of R package (default: NULL) |
generates CRAN badge link
Badge Github Actions
use_badge_ghactions(repo = NULL, user = "KWB-R", branch = NULL)use_badge_ghactions(repo = NULL, user = "KWB-R", branch = NULL)
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
branch |
default: NULL (i.e. use "default" branch) or user defined branch (e.g. "dev") |
generates Github Actions badges link
Badge Github Actions Pkgdown
use_badge_ghactions_pkgdown(repo = NULL, user = "KWB-R", branch = NULL)use_badge_ghactions_pkgdown(repo = NULL, user = "KWB-R", branch = NULL)
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
branch |
default: NULL (i.e. use "default" branch) or user defined branch (e.g. "dev") |
generates Github Actions Pkgdown badge link
Badge Github Actions RCMD Check
use_badge_ghactions_rcmdcheck(repo = NULL, user = "KWB-R", branch = NULL)use_badge_ghactions_rcmdcheck(repo = NULL, user = "KWB-R", branch = NULL)
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
branch |
default: NULL (i.e. use "default" branch) or user defined branch (e.g. "dev") |
generates travis badge link
Badge lifecycle
use_badge_lifecycle(stage = "experimental")use_badge_lifecycle(stage = "experimental")
stage |
badge declares the developmental stage of a package, according to [https://www.tidyverse.org/lifecycle/](https://www.tidyverse.org/lifecycle/), valid arguments are: "experimental", "maturing", "stable", "retired", "archived", "dormant", "questioning"), (default: "experiment") |
generates lifecycle badge link
Badge R-Universe
use_badge_runiverse(repo = NULL, user = "KWB-R")use_badge_runiverse(repo = NULL, user = "KWB-R")
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
generates codecov badge link
Badge travis
use_badge_travis(repo = NULL, user = "KWB-R")use_badge_travis(repo = NULL, user = "KWB-R")
repo |
name of repository (default: NULL) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: KWB-R") |
generates travis badge link
Adds codecov.yml
use_codecov()use_codecov()
writes codecov.yml and adds it .Rbuildignore
Use DESCRIPTION with KWB styling
use_description( author = kwb_author("rustler"), pkg = kwb_package("kwb.umberto"), version = NULL, license = "MIT + file LICENSE", copyright_holder_name = kwb_string(), funder = NULL )use_description( author = kwb_author("rustler"), pkg = kwb_package("kwb.umberto"), version = NULL, license = "MIT + file LICENSE", copyright_holder_name = kwb_string(), funder = NULL )
author |
author information in list format (default: kwb.pkgbuild:::kwb_author("rustler")) |
pkg |
package description in list format (default: kwb.pkgbuild:::kwb_package("kwb.umberto")) |
version |
user defined version number (e.g. 0.1.0) or default version number 0.0.0.9000 in case (version = NULL) of first release |
license |
license (default: "MIT + file LICENSE") |
copyright_holder_name |
name of copyright holder (default: kwb.pkgbuild:::kwb_string()) |
funder |
funder/funding agency of R package (default: NULL), e.g. project name (e.g. AQUANES) |
writes DESCRIPTION file using usethis::use_description() with KWB style
Adds default .github/workflows/
use_ghactions()use_ghactions()
writes .github/workflows/ and adds it .Rbuildignore
Adds .gitlab-ci.yml (if repo contains on root in a "gh-pages" branch)
use_gitlab_ci_blogdown( dest_dir = getwd(), yml_vector = gitlab_ci_template_blogdown() )use_gitlab_ci_blogdown( dest_dir = getwd(), yml_vector = gitlab_ci_template_blogdown() )
dest_dir |
directoy to write (default: getwd()) |
yml_vector |
a yml imported as string vector (default: gitlab_ci_template_blogdown()) |
writes .gitlab-ci.yml
Adds .gitlab-ci.yml (if repo contains a "docs" subfolder)
use_gitlab_ci_docs(dest_dir = getwd(), yml_vector = gitlab_ci_template_docs())use_gitlab_ci_docs(dest_dir = getwd(), yml_vector = gitlab_ci_template_docs())
dest_dir |
directoy to write (default: getwd()) |
yml_vector |
a yml imported as string vector (default: gitlab_ci_template_docs()) |
writes .gitlab-ci.yml and adds it .Rbuildignore
Adds .gitlab-ci.yml (which should be saved in root dir of "gh-pages" branch)
use_gitlab_ci_ghpages( dest_dir = getwd(), yml_vector = gitlab_ci_template_ghpages() )use_gitlab_ci_ghpages( dest_dir = getwd(), yml_vector = gitlab_ci_template_ghpages() )
dest_dir |
directoy to write (default: getwd()) |
yml_vector |
a yml imported as string vector (default: gitlab_ci_template_ghpages()) |
writes .gitlab-ci.yml
Adds .gitlab-ci.yml
use_gitlab_ci_pkgdown( dest_dir = getwd(), yml_vector = gitlab_ci_template_pkgdown() )use_gitlab_ci_pkgdown( dest_dir = getwd(), yml_vector = gitlab_ci_template_pkgdown() )
dest_dir |
directoy to write (default: getwd()) |
yml_vector |
a yml imported as string vector (default: gitlab_ci_template_pkgdown(), where "<owner>/<repo>" is replaced with value from DESCRIPTION specified in field URL, e.g. https://github.com/KWB-R/kwb.pkgbuild" sets "KWB-R/kwb.pkgbuild" as "<owner>/<repo>") |
writes .gitlab-ci.yml
Use index.md (used for pkgdown::build_home())
use_index_md(user = "KWB-R", domain = "github", stage = "experimental")use_index_md(user = "KWB-R", domain = "github", stage = "experimental")
user |
user name or organisation under which repository defined in |
domain |
under which repository is hosted (default: "github") |
stage |
badge declares the developmental stage of a package, according to [https://www.tidyverse.org/lifecycle/](https://www.tidyverse.org/lifecycle/), valid arguments are: "experimental", "maturing", "stable", "retired", "archived", "dormant", "questioning"), (default: "experiment") |
generates travis badge link
Helper function: describe pkg installation in index.Rmd / README.md
use_installation(pkgname, user, domain)use_installation(pkgname, user, domain)
pkgname |
package name |
user |
user name or organisation under which repository defined in parameter "repo" is hosted |
domain |
under which repository is hosted |
Create MIT licence with KWB style
use_mit_license( copyright_holder = list(name = kwb_string(), start_year = NULL) )use_mit_license( copyright_holder = list(name = kwb_string(), start_year = NULL) )
copyright_holder |
list with name of copyright holder and additional start_year (e.g. "2017") of copyright protection. If not specified (start_year = NULL), the current year is used as year only! (default: "list(name = kwb.pkgbuild:::kwb_string(), start_year = NULL)") |
creates MIT licence file
Create KWB-styled "NEWS.md"
use_news_md( news_txt = "* Added a `NEWS.md` file to track changes to the package.", style_guide_url = "https://style.tidyverse.org/news.html" )use_news_md( news_txt = "* Added a `NEWS.md` file to track changes to the package.", style_guide_url = "https://style.tidyverse.org/news.html" )
news_txt |
text added to news (default: "* Added a 'NEWS.md' file to track changes to the package.") |
style_guide_url |
refer to tidyverse style website documenting how to write a good "NEWS.md"(default: "https://style.tidyverse.org/news.html") |
writes "NEWS.md" (in case it is not existing)
Wrapper function for preparing R package with KWB styling
use_pkg( author = kwb_author("rustler"), pkg = kwb_package("kwb.umberto"), version = "0.0.0.9000", license = "MIT + file LICENSE", copyright_holder = list(name = kwb_string(), start_year = NULL), funder = NULL, user = "KWB-R", domain = "github", stage = "experimental", auto_build_pkgdown = FALSE, dbg = TRUE, ... )use_pkg( author = kwb_author("rustler"), pkg = kwb_package("kwb.umberto"), version = "0.0.0.9000", license = "MIT + file LICENSE", copyright_holder = list(name = kwb_string(), start_year = NULL), funder = NULL, user = "KWB-R", domain = "github", stage = "experimental", auto_build_pkgdown = FALSE, dbg = TRUE, ... )
author |
author information in list format (default: kwb.pkgbuild:::kwb_author("rustler")) |
pkg |
package description in list format (default: kwb.pkgbuild:::kwb_package("kwb.umberto")) |
version |
user defined version number (e.g. 0.1.0) or default "0.0.0.9000" version number for initial development version (default: "0.0.0.9000") |
license |
license (default: "MIT + file LICENSE") |
copyright_holder |
list with name of copyright holder and additional start_year (e.g. "2017") of copyright protection. If not specified (start_year = NULL), the current year is used as year only! (default: "list(name = kwb.pkgbuild:::kwb_string(), start_year = NULL)") |
funder |
funder/funding agency of R package (default: NULL), e.g. project name (e.g. AQUANES) |
user |
user name or organisation under which repository defined in parameter "repo" is hosted (default: "KWB-R") |
domain |
under which repository is hosted (default: "github") |
stage |
badge declares the developmental stage of a package, according to [https://www.tidyverse.org/lifecycle/](https://www.tidyverse.org/lifecycle/), valid arguments are: "experimental", "maturing", "stable", "retired", "archived", "dormant", "questioning"), (default: "experiment") |
auto_build_pkgdown |
prepare Travis for pkgdown::build_site() (default: FALSE), only possible if GITHUB repo already existing |
dbg |
print debug messages (default: TRUE) |
... |
additional arguments passed to use_autopkgdown() (only releveant if "auto_build_pkgdown" == TRUE) |
writes DESCRIPTION file using usethis::use_description() with KWB style
Use Package Skeleton
use_pkg_skeleton(pkg_name)use_pkg_skeleton(pkg_name)
pkg_name |
name of R package |
creates pkg skeleton in current working directory
## valid pkg folder pkg_name <- "pkgname" pkg_dir <- file.path(tempdir(), pkg_name) pkg_dir <- create_pkg_dir(pkg_dir) withr::with_dir(pkg_dir, {use_pkg_skeleton(pkg_name)})## valid pkg folder pkg_name <- "pkgname" pkg_dir <- file.path(tempdir(), pkg_name) pkg_dir <- create_pkg_dir(pkg_dir) withr::with_dir(pkg_dir, {use_pkg_skeleton(pkg_name)})
pkgdown for KWB
use_pkgdown( author = kwb_author("rustler"), copyright_holder_name = kwb_string(), pkg = get_pkgname(), user = "kwb-r", domain = "github" )use_pkgdown( author = kwb_author("rustler"), copyright_holder_name = kwb_string(), pkg = get_pkgname(), user = "kwb-r", domain = "github" )
author |
list of author attributes (default: kwb.pkgbuild:::kwb_author("rustler")) |
copyright_holder_name |
name of copyright holder (default: kwb.pkgbuild:::kwb_string()) |
pkg |
name of KWB package (default: get_pkgname()) |
user |
name of GitHub user/organisation (default: 'kwb-r') |
domain |
name of domain for webpage publishing (default: 'github') |
performs usethis::use_pkgdown() and additionally writes _pkgdown.yml based on KWB styling
Use README
use_readme_md(user = "KWB-R", domain = "github", stage = "experimental")use_readme_md(user = "KWB-R", domain = "github", stage = "experimental")
user |
user name or organisation under which repository defined in |
domain |
under which repository is hosted (default: "github") |
stage |
badge declares the developmental stage of a package, according to [https://www.tidyverse.org/lifecycle/](https://www.tidyverse.org/lifecycle/), valid arguments are: "experimental", "maturing", "stable", "retired", "archived", "dormant", "questioning"), (default: "experiment") |
generates README.md
Write to .gitignore
write_to_gitignore(ignore_pattern, comment = NULL)write_to_gitignore(ignore_pattern, comment = NULL)
ignore_pattern |
pattern that should be added to .Rbuildignore |
comment |
optional comment to write to file before the ignore pattern #' (default: NULL) |
.gitignore created/updated with pattern
Write to .Rbuildignore
write_to_rbuildignore(ignore_pattern, comment = NULL)write_to_rbuildignore(ignore_pattern, comment = NULL)
ignore_pattern |
pattern that should be added to .Rbuildignore |
comment |
optional comment to write to file before the ignore pattern (default: NULL) |
.Rbuildignore created/updated with pattern