rcompendium
makes easier the creation of R packages or research compendia (i.e. a predefined files/folders structure) so that users can focus on the code/analysis instead of wasting time organizing files. A full ready-to-work structure is set up with some additional features: version control, remote repository creation, CI/CD configuration (check package integrity under several OS, test code with testthat
, and build and deploy website using pkgdown
).
Before using the package rcompendium
you must follow these three steps.
First ensure that GIT is correctly installed on your machine and linked to RStudio. Read the Chapter 6 of Happy Git and GitHub for the useR.
You also need to store your GIT credentials locally (i.e. for the project) or globally (recommended). Run gh::gh_whoami()
to see if your git and associated credentials are correctly configured. 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.
To create the GitHub repository directly from R, the package rcompendium
uses the function usethis::use_github()
, a 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:
~/.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"
}
Then you will be able to create a GitHub repository directly from R!
You can use the arguments given
, family
, email
, and orcid
directly with the functions new_*()
and add_*()
. But if you create a lot a projects (packages and/or compendia) it can be frustrating in the long run.
An alternative way 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
while calling any function of the package, rcompendium
will search their values in this file. It will save your time (it’s the purpose of this package).
Even if you have stored your credentials in the ~/.Rprofile
file you will always be able to modify them on-the-fly (i.e. by using credentials arguments in the functions new_*()
and add_*()
) or permanently by re-running set_credentials()
.
The recommended workflow is:
set_credentials()
(if not already done);new_package()
to create a new package structure or new_compendium()
to create a new research compendium structure;DESCRIPTION
, CITATION
, and README.Rmd
;In addition to these three setup functions (set_credentials()
, new_package()
, new_compendium()
), the package rcompendium
offers 29 other functions. These can be grouped as:
add_*()
: functions to add/update/overwrite files, configuration settings, dependencies, badges, etc.;get_*()
: functions to retrieve some information (available licenses, R version, etc.).Visit the Reference page for further details.
To sum up
## Define ONCE FOR ALL your credentials ----
rcompendium::set_credentials(given = "John", family = "Doe",
email = "john.doe@domain.com",
orcid = "9999-9999-9999-9999", protocol = "ssh")
## CREATE A NEW EMPTY RSTUDIO PROJECT ----
## Create an R package structure ----
rcompendium::new_package()
## Then...
## ... edit metadata in DESCRIPTION, CITATION, README.Rmd, etc.
## ... implement and document R functions in R/
## Update functions documentation and NAMESPACE ----
devtools::document()
## Update list of dependencies in DESCRIPTION ----
rcompendium::add_dependencies()
## Check package ----
devtools::check()
## Example: use of an add_*() function ...
## ... update 'Number of Dependencies Badge' in README.Rmd ----
rcompendium::add_dependencies_badge()
N.B. Users can also use functions from the package usethis
to add some missing features (e.g. data/
and package release tools).
You are welcome to contribute to the rcompendium
project. Please read our Contribution Guidelines.
Please note that the rcompendium
project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
This package is the result of intense discussions and feedback from the training course Data Toolbox for Reproducible Research in Computational Ecology.
rcompendium
is largely inspired by the package rrtools
developed by Ben Marwick et al. and tries to respect the standard defined by the community. Special thanks to these developers!