devtools: To Develop Packages

https://devtools.r-lib.org/

# Install devtools from CRAN
install.packages("devtools")
# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/devtools")

library("devtools")

roxygen2: To Document the Code

https://roxygen2.r-lib.org/

# Install devtools from CRAN
install.packages("roxygen2")
# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/roxygen2")

library("roxygen2")

roxygen2: To Document the Code

#' Add to message on top of a call to `print()`
#'
#' This function print a greeting message on top of
#' the regular call to `print()`.
#'
#' @inheritParams print
#' @param msg A string to print as a greeting message
#' @export
#' @examples
#' print_msg(1, "The value is: ")
print_msg <- function(x, msg) {
  message(msg)
  x
}

usethis: To Setup the Environment

https://usethis.r-lib.org/

# Install devtools from CRAN
install.packages("usethis")
# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/usethis")

library("usethis")

usethis: To Setup the Environment

Global options for usethis:

options(
  usethis.full_name = "Firstname Lastname",
  usethis.protocol  = "ssh",
  usethis.description = list(
    `Authors@R` = 'person(
      given = "Firstname",
      family = "Lastname",
      role = c("aut", "cre"),
      email = "Firstname.Lastname@cnrs.fr",
      comment = c(ORCID = "0000-0000-0000-0000")
    )',
    Version = "0.0.0.9000"
  )
)

usethis: To Setup the Environment

Setup Git:

use_git_config(
  user.name = "Firstname Lastname", 
  user.email = "Firstname.Lastname@cnrs.fr"
)
# git_sitrep() # To check if Git is configured properly

git config --global user.name 'Firstname Lastname'
git config --global user.email 'Firstname.Lastname@cnrs.fr'
git config --global --list

usethis: To Setup the Environment

First an access token from GitHub needs to be created: https://github.com/settings/tokens

browse_github_token() # open the form in a browser
edit_r_environ() # open .Renviron file from your home

Edit the .Renviron and add your token.

GITHUB_PAT=xloltrglmlm9v0wqb4zgnks86z5uwkqgoat29aar

Restart and check if you have access to your token

Sys.getenv("GITHUB_PAT")
github_token()

usethis: A Tidy Package

library("usethis")
create_tidy_package()
function (path, name = "RStudio") {
  path <- create_package(path, rstudio = TRUE, open = FALSE)
  old_project <- proj_set(path)
  on.exit(proj_set(old_project), add = TRUE)
  use_roxygen_md()
  use_testthat()
  use_gpl3_license(name)
  use_tidy_description()
  use_readme_rmd(open = FALSE)
  use_lifecycle_badge("experimental")
  use_cran_badge()
  use_cran_comments(open = FALSE)
  use_tidy_github()
  ui_todo("In the new package, remember to do:")
  ui_todo("{ui_code('use_git()')}")
  ui_todo("{ui_code('use_github()')}")
  ui_todo("{ui_code('use_tidy_ci()')}")
  ui_todo("{ui_code('use_pkgdown()')}")
  ui_todo("{ui_code('use_pkgdown_travis()')}")
  proj_activate(path)
}

usethis: A Tidy Package

Create the package skeleton.

path <- create_package("mypackage", rstudio = TRUE, open = FALSE)

✔ Creating './'
✔ Creating 'R/'
✔ Writing 'DESCRIPTION'
Package: mypackage
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R (parsed):
    * First Last <first.last@example.com> [aut, cre] (<https://orcid.org/YOUR-ORCID-ID>)
Description: What the package does (one paragraph).
License: What license it uses
Encoding: UTF-8
LazyData: true
✔ Writing 'NAMESPACE'
✔ Writing 'mypackage.Rproj'
✔ Adding '.Rproj.user' to '.gitignore'
✔ Adding '^mypackage\\.Rproj$', '^\\.Rproj\\.user$' to '.Rbuildignore'

usethis: A Tidy Package

Setup Rstudio project (rstudio = TRUE from create_package()).

old_project <- proj_set(path)
on.exit(proj_set(old_project), add = TRUE)

usethis: A Tidy Package

Setup roxygen2 as tool to render documentation.

use_roxygen_md()

✔ Setting Roxygen field in DESCRIPTION to 'list(markdown = TRUE)'
✔ Setting RoxygenNote field in DESCRIPTION to '7.0.2'
● Run `devtools::document()`

usethis: A Tidy Package

Setup unit test directory with default scripts.

use_testthat()

✔ Adding 'testthat' to Suggests field in DESCRIPTION
✔ Creating 'tests/testthat/'
✔ Writing 'tests/testthat.R'
● Call `use_test()` to initialize a basic test file and open it for editing.

usethis: A Tidy Package

Setup licence (several available).

use_gpl3_license("mypackage")

✔ Setting License field in DESCRIPTION to 'GPL-3 + file LICENSE'
✔ Writing 'LICENSE.md'
✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'
✔ Writing 'LICENSE'

usethis: A Tidy Package

Format/clean DESCRIPTION file.

use_tidy_description()

Add version for packages listed in DESCRIPTION (e.g., Imports field).

use_tidy_versions()

usethis: A Tidy Package

Add an Rmarkdown script to render the README.md file.

use_readme_rmd(open = FALSE)

✔ Writing 'README.Rmd'
✔ Adding '^README\\.Rmd$' to '.Rbuildignore'

usethis: A Tidy Package

Add a development status badge following tidyverse convention.

use_lifecycle_badge("experimental")

✔ Adding Lifecycle: experimental badge to 'README.Rmd'
● Re-knit 'README.Rmd

usethis: A Tidy Package

Add a CRAN badge displaying CRAN version.

use_cran_badge()

✔ Adding CRAN status badge to 'README.Rmd'
● Re-knit 'README.Rmd'

usethis: A Tidy Package

Add a markdown file (used for the release to CRAN).

use_cran_comments(open = FALSE)

✔ Writing 'cran-comments.md'
✔ Adding '^cran-comments\\.md$' to '.Rbuildignore'

usethis: A Tidy Package

Add default files to use in GitHub (Check them).
Note: github/SUPPORT.md must be edited to fix GitHub repository at line 23.

use_tidy_github()

✔ Creating '.github/'
✔ Adding '^\\.github$' to '.Rbuildignore'
✔ Writing '.github/CONTRIBUTING.md'
✔ Creating '.github/ISSUE_TEMPLATE/'
✔ Adding '^\\.github/ISSUE_TEMPLATE$' to '.Rbuildignore'
✔ Writing '.github/ISSUE_TEMPLATE/issue_template.md'
✔ Writing '.github/SUPPORT.md'
✔ Writing '.github/CODE_OF_CONDUCT.md'
● Don't forget to describe the code of conduct in your README:
  Please note that the 'mypackage' project is released with a
  [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).
  By contributing to this project, you agree to abide by its terms.
  [Copied to clipboard]

usethis: A Tidy Package

ui_todo("In the new package, remember to do:")
ui_todo("{ui_code('use_git()')}")
ui_todo("{ui_code('use_github()')}")
ui_todo("{ui_code('use_tidy_ci()')}")
ui_todo("{ui_code('use_pkgdown()')}")
ui_todo("{ui_code('use_pkgdown_travis()')}")

● In the new package, remember to do:
● `use_git()`
● `use_github()`
● `use_tidy_ci()`
● `use_pkgdown()`
● `use_pkgdown_travis()`

usethis: A Tidy Package

Open the newly created package as an Rstudio project.

proj_activate(path)

✔ Opening 'C:/mypackage' in new RStudio session

usethis: A Tidy Package

Setup the package to use Git.

use_git()

✔ Initialising Git repo
✔ Adding '.Rhistory', '.RData' to '.gitignore'
There are 11 uncommitted files:
  '.github/'
  '.gitignore'
  '.Rbuildignore'
  'cran-comments.md'
  'DESCRIPTION'
  'LICENSE'
  'LICENSE.md'
  'mypackage.Rproj'
  'NAMESPACE'
  'README.Rmd'
  'tests/'
Is it ok to commit them?
1: I agree
2: Not now
3: No way

usethis: A Tidy Package

Setup a repository on GitHub for the package.

use_github()

✔ Setting active project to 'C:/mypackage'
✔ Checking that current branch is 'master'
● Check title and description
  Name:        mypackage
  Description: What the Package Does (One Line, Title Case)
Are title and description ok?
1: Negative
2: Absolutely not
3: Yup

usethis: A Tidy Package

Setup continuous integration using travis-CI and code coverage.

use_tidy_ci()

✔ Writing '.travis.yml'
✔ Adding '^\\.travis\\.yml$' to '.Rbuildignore'
✔ Writing 'codecov.yml'
✔ Adding '^codecov\\.yml$' to '.Rbuildignore'
✔ Adding 'R' to Depends field in DESCRIPTION
✔ Adding 'covr' to Suggests field in DESCRIPTION
✔ Adding '^\\.covrignore$' to '.Rbuildignore'
✔ Adding 'R/deprec-*.R', 'R/compat-*.R' to '.covrignore'
✔ Adding Travis build status badge to 'README.Rmd'
● Re-knit 'README.Rmd'
✔ Adding Codecov test coverage badge to 'README.Rmd'
● Re-knit 'README.Rmd'
✔ Replacing release environment in 'cran-comments.md'
● Turn on travis for your repo at https://travis-ci.org/profile/user

usethis: A Tidy Package

Add utils for tidy-evaluation (e.g., .data pronoun).

use_tidy_eval()

✔ Adding 'roxygen2' to Suggests field in DESCRIPTION
✔ Adding 'rlang' to Imports field in DESCRIPTION
✔ Writing 'R/utils-tidy-eval.R'
● Run `devtools::document()`

usethis: A Tidy Package

Add pipe (%>%).

use_pipe()

✔ Adding 'magrittr' to Imports field in DESCRIPTION
✔ Writing 'R/utils-pipe.R'
● Run `devtools::document()` to update 'NAMESPACE'

usethis: A Tidy Package

Add the package stats to the package.

use_package("stats")

✔ Adding 'stats' to Imports field in DESCRIPTION
● Refer to functions with `stats::fun()`

devtools: To Build / Check / Test

Frequent development tasks:

• load_all() simulates installing and reloading your package, loading code in R/, compiled shared objects in src/ and data files in data/.

• document() updates generated documentation in man/, file collation and NAMESPACE.

• test() reloads your code with load_all(), then runs all testthat tests.

• test_coverage() runs test coverage on your package with covr.

devtools: Build / Check / Test

Building and installing:

• install() reinstalls the package, detaches the currently loaded version then reloads the new version with library().

• build() builds a package file from package sources. You can use it to build a binary version of your package.

devtools: Build / Check / Test

Check and release:

• check() updates the documentation, then builds and checks the package locally.
  check_win() checks a package using win-builder, and check_rhub() checks a package using r-hub. This allows you to easily check your package on all systems CRAN uses before submission.

• release() makes sure everything is ok with your package (including asking you a number of questions), then builds and uploads to CRAN.

Render the README.md

Before trying to render the README.Rmd, set the chunk with library(mypackage) to eval = FALSE.

rmarkdown::render('README.Rmd',  encoding = 'UTF-8')

Update the Code Documentation

document()

Updating mypackage documentation
Writing NAMESPACE
Loading mypackage
Writing NAMESPACE
Writing pipe.Rd
Writing tidyeval.Rd

Check the Package

check()

-- R CMD check results ---------------------------------------------------------- mypackage 0.0.0.9000 ----
Duration: 19.6s
> checking tests ...
  See below...
-- Test failures ---------------------------------------------------------------------------- testthat ----
> library(testthat)
> library(mypackage)
> 
> test_check("mypackage")
Error: No tests found for mypackage
Execution halted
1 error x | 0 warnings √ | 0 notes √