new_package: Create an R package structure
In FRBCesab/rcompendium: Create a Package or Research Compendium Structure

new_package

R Documentation

Create an R package structure

Description

This function creates a new R package structure according to the current best practices. Essential features of an R package are created (DESCRIPTION and NAMESPACE files, and ⁠R/⁠ and ⁠man/⁠ folders). The project is also versioned with git and a generic R .gitignore is added.

IMPORTANT - Before using this function user needs to create a new folder (or a new project if using RStudio) and run this function inside this folder (by using setwd() or by opening the Rproj in a new RStudio session). The name of the package will be the same as the name of this folder. Some rules must be respected: https://r-pkgs.org/workflow101.html#name-your-package.

Some fields of the DESCRIPTION file (maintainer information, package name, license, URLs, and roxygen2 version) are automatically filled but others (like title and description) need to be edited manually.

Additional features are also created: a CITATION file, a README.Rmd, and ⁠tests/⁠ and ⁠vignettes/⁠ folders (optional). See the vignette Get started for a complete overview of the full structure.

A GitHub repository can also be created (default) following the "GitHub last" workflow (https://happygitwithr.com/existing-github-last.html). Configuration files for GitHub Actions to automatically 1) check the package, 2) test and report code coverage, and 3) deploy the website using pkgdown will be added in the ⁠.github/⁠ folder. See below the section Creating a GitHub repo.

Usage

new_package(
  license = "GPL (>= 2)",
  status = NULL,
  lifecycle = NULL,
  contributing = TRUE,
  code_of_conduct = TRUE,
  vignette = TRUE,
  test = TRUE,
  create_repo = TRUE,
  private = FALSE,
  gh_check = TRUE,
  codecov = TRUE,
  website = TRUE,
  gh_render = TRUE,
  gh_citation = TRUE,
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  organisation = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

`license`	A character vector of length 1. The license to be used for this package. Run `get_licenses()` to choose an appropriate one. Default is `license = 'GPL (>= 2)'` The license can be changed later by calling `add_license()` (and `add_license_badge()` or `refresh()` to update the corresponding badge in the README).
`status`	A character vector of length 1. The status of the project according to the standard defined by the https://www.repostatus.org project. One among `'concept'`, `'wip'`, `'suspended'`, `'abandoned'`, `'active'`, `'inactive'`, or `'unsupported'`. See `add_repostatus_badge()` for further information. This argument is used to add a badge to the `README.Rmd` to help visitors to better understand your project. If you don't want this badge use `status = NULL` (default). This status can be added/changed later by using `add_repostatus_badge()`.
`lifecycle`	A character vector of length 1. The life cycle stage of the project according to the standard defined at https://lifecycle.r-lib.org/articles/stages.html. One among `'experimental'`, `'stable'`, `'deprecated'`, or `'superseded'`. See `add_lifecycle_badge()` for further information. This argument is used to add a badge to the `README.Rmd` to help visitors to better understand your project. If you don't want this badge use `lifecycle = NULL` (default). This stage can be added/changed later by using `add_lifecycle_badge()`.
`contributing`	A logical value. If `TRUE` (default) adds a `CONTRIBUTING.md` file and `ISSUE_TEMPLATES`. See `add_contributing()` for further information.
`code_of_conduct`	A logical value. If `TRUE` (default) adds a `CODE_OF_CONDUCT.md` file. See `add_code_of_conduct()` for further information.
`vignette`	A logical value. If `TRUE` (default) creates a vignette in `⁠vignettes/⁠`. Packages `knitr` and `rmarkdown` are also added to the `Suggests` field in the `DESCRIPTION` file.
`test`	A logical value. If `TRUE` (default) initializes units tests by running `usethis::use_testthat()`. Package `testthat` is also added to the `Suggests` field in the `DESCRIPTION` file.
`create_repo`	A logical value. If `TRUE` (default) creates a repository (public if `private = FALSE` or private if `private = TRUE`) on GitHub. See below the section Creating a GitHub repo.
`private`	A logical value. If `TRUE` creates a private repository on user GitHub account (or organisation). Default is `private = FALSE`.
`gh_check`	A logical value. If `TRUE` (default) configures GitHub Actions to automatically check and test the package after each push. This will run `⁠R CMD check⁠` on the three major operating systems (Ubuntu, macOS, and Windows) on the latest release of R. See `add_github_actions_check()` for further information. If `create_repo = FALSE` this argument is ignored.
`codecov`	A logical value. If `TRUE` (default) configures GitHub Actions to automatically report the code coverage of units tests after each push. See `add_github_actions_codecov()` for further information. If `create_repo = FALSE` this argument is ignored.
`website`	A logical value. If `TRUE` (default) configures GitHub Actions to automatically build and deploy the package website (using `pkgdown`) after each push. A gh-pages branch will be created using `usethis::use_github_pages()` and the GitHub repository will be automatically configured to deploy website. If `create_repo = FALSE` this argument is ignored.
`gh_render`	A logical value. If `TRUE` (default) configures GitHub Actions to automatically knit the `README.Rmd` after each push. See `add_github_actions_render()` for further information. If `create_repo = FALSE` this argument is ignored.
`gh_citation`	A logical value. If `TRUE` (default) configures GitHub Actions to automatically update the `CITATION.cff` file. See `add_github_actions_citation()` for further information. If `create_repo = FALSE` this argument is ignored.
`given`	A character vector of length 1. The given name of the maintainer of the package. If `NULL` (default) the function will try to get this value by reading the `.Rprofile` file. For further information see `set_credentials()` and below the section Managing credentials.
`family`	A character vector of length 1. The family name of the maintainer of the package. If `NULL` (default) the function will try to get this value by reading the `.Rprofile` file. For further information see `set_credentials()` and below the section Managing credentials.
`email`	A character vector of length 1. The email address of the maintainer of the package. If `NULL` (default) the function will try to get this value by reading the `.Rprofile` file. For further information see `set_credentials()` and below the section Managing credentials.
`orcid`	A character vector of length 1. The ORCID of the maintainer of the package. If `NULL` (default) the function will try to get this value by reading the `.Rprofile` file. For further information see `set_credentials()` and below the section Managing credentials.
`organisation`	A character vector of length 1. The GitHub organisation to host the repository. If defined it will overwrite the GitHub pseudo. Default is `organisation = NULL` (the GitHub pseudo will be used).
`overwrite`	A logical value. If `TRUE` files written from templates and modified by user are erased. Default is `overwrite = FALSE`. Be careful while using this argument.
`quiet`	A logical value. If `TRUE` messages are deleted. Default is `FALSE`.

Value

No return value.

Recommended workflow

The purpose of the package rcompendium is to make easier the creation of R package/research compendium so that user can focus on the code/analysis instead of wasting time organizing files.

The recommended workflow is:

Create an empty RStudio project;
Store your credentials with set_credentials() (if not already done);
Run new_package() to create a new package structure (and the GitHub repository);
Edit some metadata in DESCRIPTION, CITATION, and README.Rmd;
Implement, document & test functions (the fun part);
Update the project (update .Rd files, NAMESPACE, external dependencies in DESCRIPTION, re-knit README.Rmd, and check package integrity) with refresh();
Repeat steps 5 and 6 while developing the package.

Managing credentials

You can use the arguments given, family, email, and orcid directly with the function new_package() (and others). But if you create a lot a projects (packages and/or compendiums) it can be frustrating in the long run.

An alternative is to use ONCE AND FOR ALL the function set_credentials() to permanently store this information in the .Rprofile file. If these arguments are set to NULL (default) each function of the package rcompendium will search in this .Rprofile file. It will save your time (it's the purpose of this package).

Even if you have stored your information in the .Rprofile file you will always be able to modify them on-the-fly (i.e. by using arguments of the new_package()) or permanently by re-running set_credentials().

Configuring git

First run gh::gh_whoami() to see if your git is correctly configured. If so you should see something like:

{
  "name": "John Doe",
  "login": "jdoe",
  "html_url": "https://github.com/jdoe",
  ...
}

Otherwise you might need to run:

gert::git_config_global_set(name  = "user.name", 
                            value = "John Doe")
                            
gert::git_config_global_set(name  = "user.email", 
                            value = "john.doe@domain.com")
                            
gert::git_config_global_set(name  = "github.user", 
                            value = "jdoe")

See gert::git_config_global_set() for further information.

Creating a GitHub repo

To create the GitHub repository directly from R, the package rcompendium uses the function usethis::use_github(), an client to the GitHub REST API. The interaction with this API required an authentication method: a GITHUB PAT (Personal Access Token).

If you don't have a GITHUB PAT locally stored, you must:

Obtain a new one from your GitHub account. Make sure to select at least the first two scopes (private repository and workflow)
Store it in the ⁠~/.Renviron⁠ file by using usethis::edit_r_environ() and adding the following line: GITHUB_PAT='ghp_99z9...z9'

Run usethis::gh_token_help() for more information about getting and configuring a GITHUB PAT.

If everything is well configured you should see something like this after calling gh::gh_whoami():

{
  "name": "John Doe",
  "login": "jdoe",
  "html_url": "https://github.com/jdoe",
  "scopes": "delete_repo, repo, workflow",
  "token": "ghp_99z9...z9"
}

And you will be able to create a GitHub repository directly from R!

Examples

## Not run: 
library(rcompendium)

## Define **ONCE FOR ALL** your credentials ----
set_credentials(given = "John", family = "Doe", 
                email = "john.doe@domain.com", 
                orcid = "9999-9999-9999-9999", protocol = "ssh")

## Create an R package ----
new_package()

## Start developing functions ----
## ...

## Update package (documentation, dependencies, README, check) ----
refresh()

## End(Not run)

FRBCesab/rcompendium documentation built on Nov. 15, 2024, 9:38 p.m.