vignettes/tutorial.Rmd
tutorial.Rmd
This tutorial explains how to setup an R package so that it complies with a default style. We would like to apply this default style to all KWB-packages that are hosted on our GitHub account KWB-R. The aim is to present all packages in a common manner (consistent DESCRIPTION and documentation) and to use the same services (continuous integration, code coverage) for all our packages.
This package provides functions to:
Before you can use the package kwb.pkgdown you need to
Install required packages that are not yet available in your local R user library from CRAN:
# Get the names of already installed packages
installed_packages <- rownames(installed.packages())
# Define the names of required packages:
# - remotes: functions to install R packages from Github
# - pkgdown: functions to create a package website
required_packages <- c("remotes", "pkgdown")
# Determine the packages that are not yet installed
packages_to_install <- setdiff(required_packages, installed_packages)
# Install the packages from CRAN
for (package in packages_to_install) {
install.packages(package, repos = "https://cloud.r-project.org")
}
The remotes package that should now be installed, allows to install packages directly from GitHub. Therefore, the functions from this package need to communicate with the GitHub server. As it is best for users to get explicitly authenticated by the GitHub server we will set a so called Private Access Token (PAT) in the following. This token will then automatically be used whenever the GitHub server is accessed. Please see the Installation vignette first to learn how to get your personal GitHub PAT and use that token instead of Put your Private Access Token here
in the following command:
Now, that the access token is set, you can use install_github()
from the remotes packages to install packages directly from GitHub. Let’s start by installing a fully working version of the remotes package itself (unfortunately, the current CRAN version as installed above contains a bug…):
Finally we can install the latest version of this package from our GitHub account:
Secondly you need to personalise your R package by adapting a default template that we provide for KWB packages. This template is contained in the R package kwb.pkgbuild
.
In the best case, your package will be under version control. We encourage you to create a GitHub repository on our GitHub account that represents the package. Having a package as a repository on GitHub has the advantage that it can be easily installed directly from there with no more than running remotes::install_github("kwb-r/<package_name>")
. Once you have created the GitHub repository, clone it to a folder on your local machine.
You can let RStudio do the cloning for you. Therefore,
https://github.com/kwb-r/<package_name>
,<package_name>
(this should be the default),~/github-repos
.For the steps described in the following, you need to provide the name of the package in a variable package
and the path to the local directory to which GitHub repositories are cloned in a variable repo_dir
:
# Set the path to the package directory
pkg_dir <- file.path(repo_dir, package)
# Create directory for R package
kwb.pkgbuild::create_pkg_dir(pkg_dir)
#> /tmp/RtmpmvHKFo/kwb.newpackage is a valid 'root_dir' for pkg 'kwb.newpackage'
#> Warning: `recursive` is deprecated, please use `recurse` instead
#> [1] "/tmp/RtmpmvHKFo/kwb.newpackage"
# Create a default package structure
withr::with_dir(pkg_dir, {kwb.pkgbuild::use_pkg_skeleton(package)})
#> ✔ Setting active project to '/tmp/RtmpmvHKFo/kwb.newpackage'
#> ✔ Writing 'kwb.newpackage.Rproj'
#> ✔ Adding '.Rproj.user' to '.gitignore'
In the following, we present the commands required to setup and create your new package. We suggest that you write the corresponding code into a .R
script file (e.g. setup_package.R
). Once the package is created, we suggest to put the script file into the inst/extdata
folder of your package. This makes the creation of the package reproducible and can be used as a template for the creation of further packages.
The package description needs three entries
name: name of the package
title: title of your R package (which is automatically converted to title case with the function tools::toTitleCase()
)
desc: package description. Should be at least one sentence long and needs to end with a period!
Running the following code not only creates an R package structure but also adds some KWB-R specfic styling, e.g.:
Adding configution files for:
Continous integration on windows (https://appveyor.com) and linux (https://travis-ci.org/KWB-R)
Code coverage in R package using the servive codecov.io
Backup of Github repositories on our mirrored KWB-R group on Gitlab
Indicates the current lifecycle of the R package according to https://www.tidyverse.org/lifecycle/
Uses by default the permissive for all public R packages currently hosted on Github (see: http://kwb-r.github.io/status/) and lists KWB as copyright holder (see e.g. here)
Creates README
files (README.Rmd
and README.md
) for the above mentioned topics and
Prepares a KWB-R flavored documentation website template named _packagedown.yml
needed by http://pkgdown.r-lib.org/
Running the following R function will create the R package with the version
= 0.0.0.9000
and development stage experimental
(defined here).
Add your R functions in the folder R
/. By using usethis::use_r
with the parameter name
= function
an empty R script is already stored in the right folder R/
.
For writing your R code/functions please follow the tidyverse coding style (https://style.tidyverse.org/), which serves as our default KWB-R style.
Now you just need to fill it with content (i.e. your functions) and document it using roxygen2. If you have already defined a function you can add a roxygen2 skeleton by using clicking on the Insert Roxygen Skeleton
button in RStudio as shown below.
More information on documentation in R is provided here: http://r-pkgs.had.co.nz/man.html
Once you completed all the steps above go to the upper right panel in RStudio and click on Build
-> More
-> Configure build tools
as shown below.
Then click on Configure
and a new window opens. Here you select everything as shown below:
After doing so accept the settings by two times clicking Ok
.
Subsequently click the Check
button so that your package is cross-checked for possible problems (e.g. wrong documentation, missing package dependencies).
In case of missing package dependencies as shown below these should be added to the DESCRIPTION file.
Namespace dependencies not required: 'fs' 'httr' 'stringr' 'usethis' 'yaml'
See section 'The DESCRIPTION file' in the 'Writing R Extensions'
manual.
* DONE
Status: 1 ERROR
See
'C:/Users/myname/Documents/RProjects/kwb.pkgbuild.Rcheck/00check.log'
for details.
checking package dependencies ... ERROR
Namespace dependencies not required: 'fs' 'httr' 'stringr' 'usethis' 'yaml'
This can be done using the function usethis::use_package()
as shown below:
pkg_dependencies <- c('fs', 'httr', 'stringr', 'usethis', 'yaml')
sapply(pkg_dependencies, usethis::use_package)
✔ Adding 'fs' to Imports field in DESCRIPTION
● Refer to functions with `fs::fun()`
✔ Adding 'httr' to Imports field in DESCRIPTION
● Refer to functions with `httr::fun()`
✔ Adding 'stringr' to Imports field in DESCRIPTION
● Refer to functions with `stringr::fun()`
✔ Adding 'usethis' to Imports field in DESCRIPTION
● Refer to functions with `usethis::fun()`
✔ Adding 'yaml' to Imports field in DESCRIPTION
● Refer to functions with `yaml::fun()`
Subsequently you should re-click on the Check
button again and it should finish without errors.
Now you are ready for building your R package by clicking on the Install and Restart
button. A successful installation should finish with Done
as shown below:
Finally you should run pkgdown::build_site()
in order to create an documentation website for your R package. Running this command will store the website in the subfolder docs
within your R package.
Once you upload your R package to Github this can be easily used as documentation page that you define in the settings page for your R package which is available at:
https://github.com/KWB-R/ kwb.mycoolrpackage
/settings
In case you have already a Github repo defined for your R package you can also automate the process of updating the pkgdown::build_site()
by with the wrapper function kwb.pkgbuild::use_autopkgdown()
, which:
creates a new branch “gh-pages” where the documentation site is deployed
sets “docs” folder to “.gitignore” (as these files are now build on Travis)
prepares Travis-CI by:
adding secret key with travis::use_travis_deploy()
creating “.travis.yml” with kwb.pkgbuild::use_travis(auto_build_pkgdown = TRUE)
creating an empty “gh-pages” branch with kwb.pkgbuild::create_empty_branch_ghpages()
Finally to need to go to:
https://github.com/KWB-R/ kwb.mycoolrpackage
/settings
and set the “source” for Github Pages to the branch “gh-pages”. After each successful Travis build the documentation website is now also updated!