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 = "[email protected]")
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 = "[email protected]",
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!