diff --git a/NEWS.md b/NEWS.md index d6480d8..2a0c754 100644 --- a/NEWS.md +++ b/NEWS.md @@ -13,10 +13,12 @@ * `get_deps_*()` better detects project dependencies * `add_citation()` creates now two additional files: `CITATION.cff` and `.github/workflows/update-citation-cff.yaml` + * `add_compendium()` allows now the user to choose its own compendium structure * **Minor changes** * Update GitHub Actions templates (`yaml` files) + * Update README templates * The `man/` folder and `NAMESPACE` are now untracked by git (for compendium only) * Remove dependencies badge in README * Change default values of `lifecycle` and `status` arguments in `new_package()` diff --git a/R/add_compendium.R b/R/add_compendium.R index c0bd8cc..80adb3e 100644 --- a/R/add_compendium.R +++ b/R/add_compendium.R @@ -1,17 +1,18 @@ -#' Create compendium folders +#' Create additional folders #' #' @description -#' This function creates the following additional folders `data/`, `analyses/`, -#' `outputs/`, and `figures/`. Each folder has a `README.md` to provide -#' instructions. The argument `compendium` allows user to choose if these -#' folders are created at the root of the project (default) or nested inside a -#' parent directory. All theses folders are added to the `.Rbuildignore` file. -#' -#' @param compendium A character of length 1. By default, compendium folders -#' are created at the root of the project. User can change their location -#' with this argument. For instance, if `compendium = 'analysis'`, compendium -#' folders will be created inside the directory `analysis/`. +#' This function creates a compendium, i.e. additional folders to a package +#' structure. By default, the following directories are created: +#' `data/raw-data`, `data/derived-data`, `analyses/`, `outputs/`, and +#' `figures/`. A `README.md` is added to each folder and must be edited. The +#' argument `compendium` allows user to choose its own compendium structure. +#' All theses folders are added to the `.Rbuildignore` file. #' +#' @param compendium A character vector specifying the folders to be created. +#' +#' @param quiet A logical value. If `TRUE` messages are deleted. Default is +#' `FALSE`. +#' #' @return No return value. #' #' @export @@ -21,178 +22,54 @@ #' @examples #' \dontrun{ #' add_compendium() +#' add_compendium(compendium = "paper") +#' add_compendium(compendium = c("data", "outputs", "code", "manuscript")) #' } -add_compendium <- function(compendium = ".") { - - - if (is.null(compendium)) return(invisible(NULL)) - - stop_if_not_string(compendium) - - path <- path_proj() - - if (compendium != "." && compendium != getwd() && compendium != path) { - - if (length(strsplit(compendium, "/|\\\\")[[1]]) > 1) - stop("Argument 'compendium' must be a non-nested folder.") - - path <- file.path(path, compendium) - - } else { - - compendium <- NULL - } +add_compendium <- function(compendium = NULL, quiet = FALSE) { + stop_if_not_logical(quiet) - if (!dir.exists(path)) { - - dir.create(path, recursive = TRUE) - - if (!is.null(compendium)) { - - ui_done("Creating {ui_value(compendium)} directory") - add_to_buildignore(compendium) - ui_line() - } + if (is.null(compendium)) { + compendium <- c("data/raw-data", "data/derived-data", "outputs", "figures", + "analyses") } - - ## Create data/ folder ---- - - if (!dir.exists(file.path(path, "data"))) { - - dir.create(file.path(path, "data"), recursive = TRUE) - dir.create(file.path(path, "data", "raw-data"), recursive = TRUE) - dir.create(file.path(path, "data", "derived-data"), recursive = TRUE) - - readme <- c("# README", - "", - "This folder contains all raw data.", - "**Do not** modify these data") - - writeLines(readme, con = file.path(path, "data", "raw-data", "README.md")) - - readme <- c("# README", - "", - "This folder contains all derived data.") - - writeLines(readme, con = file.path(path, "data", "derived-data", - "README.md")) - - - if (!is.null(compendium)) { - - msg <- paste0(compendium, "/data/") - - } else { - - msg <- "data/" - } - - ui_done("Creating {ui_value(msg)} directory") - - if (is.null(compendium)) { - - add_to_buildignore("data") - - } else { - - add_to_gitignore(paste0(compendium, "/data")) - } - ui_line() + if (!is.character(compendium)) { + stop("Argument 'compendium' must be a character.") } + path <- path_proj() - ## Create outputs/ folder ---- - - if (!dir.exists(file.path(path, "outputs"))) { - - dir.create(file.path(path, "outputs"), recursive = TRUE) - - readme <- c("# README", - "", - "This folder contains all your results") - - writeLines(readme, con = file.path(path, "outputs", "README.md")) + for (i in 1:length(compendium)) { - - if (!is.null(compendium)) { - - msg <- paste0(compendium, "/outputs/") + if (!dir.exists(file.path(path, compendium[i]))) { - } else { + dir.create(file.path(path, compendium[i]), recursive = TRUE) - msg <- "outputs/" + if (!quiet) { + ui_done("Creating {ui_value(paste0(compendium[i], '/'))} directory") + } } - - ui_done("Creating {ui_value(msg)} directory") - - if (is.null(compendium)) add_to_buildignore("outputs") - - ui_line() - } - - - ## Create figures/ folder ---- - - if (!dir.exists(file.path(path, "figures"))) { - - dir.create(file.path(path, "figures"), recursive = TRUE) - - readme <- c("# README", - "", - "This folder contains all your figures") - - writeLines(readme, con = file.path(path, "figures", "README.md")) - - - if (!is.null(compendium)) { - - msg <- paste0(compendium, "/figures/") - - } else { - msg <- "figures/" - } - - ui_done("Creating {ui_value(msg)} directory") + add_to_buildignore(compendium, quiet = quiet) - if (is.null(compendium)) add_to_buildignore("figures") - ui_line() - } - - - ## Create analyses/ folder ---- - - if (!dir.exists(file.path(path, "analyses"))) { + if (!file.exists(file.path(path, compendium[i], "README.md"))) { - dir.create(file.path(path, "analyses"), recursive = TRUE) - - readme <- c("# README", - "", - "This folder contains all your analyses of the project.", - paste0("It contains only R scripts (R functions must be ", - "stored in the R/ folder).")) - - writeLines(readme, con = file.path(path, "analyses", "README.md")) - - - if (!is.null(compendium)) { + readme <- c("# README", + "", + "**{{ PLEASE DESCRIBE THE CONTENT OF THIS FOLDER}}**") - msg <- paste0(compendium, "/analyses/") + writeLines(readme, con = file.path(path, compendium[i], "README.md")) - } else { - - msg <- "analyses/" + if (!quiet) { + + ui_done(paste0("Adding a {ui_value('README.md')} to ", + "{ui_value(paste0(compendium[i], '/'))} directory")) + ui_line() + } } - - ui_done("Creating {ui_value(msg)} directory") - - if (is.null(compendium)) add_to_buildignore("analyses") - - ui_line() } invisible(NULL) diff --git a/R/new_compendium.R b/R/new_compendium.R index 6b5835f..4dcdbd8 100644 --- a/R/new_compendium.R +++ b/R/new_compendium.R @@ -37,10 +37,8 @@ #' All these files/folders are added to the `.Rbuildignore` so the rest of the #' project (e.g. R functions) can be used (or installed) as a R package. #' -#' @param compendium A character vector of length 1. By default, compendium -#' folders are created at the root of the project. User can change their -#' location with this argument. For instance, if `compendium = 'analysis'`, -#' compendium folders will be created inside the directory `analysis/`. +#' @param compendium A character vector specifying the folders to be created. +#' See [add_compendium()] for further information. #' #' @param license A character vector of length 1. The license to be used for #' this project. Run [get_licenses()] to choose an appropriate one. Default @@ -188,7 +186,7 @@ #' refresh() #' } -new_compendium <- function(compendium = ".", license = "GPL (>= 2)", +new_compendium <- function(compendium = NULL, license = "GPL (>= 2)", status = NULL, lifecycle = NULL, vignette = FALSE, test = FALSE, create_repo = TRUE, private = FALSE, gh_check = FALSE, codecov = FALSE, website = FALSE, @@ -419,9 +417,9 @@ new_compendium <- function(compendium = ".", license = "GPL (>= 2)", if (!quiet) ui_done("Creating {ui_value('R/')} directory") - dir.create(file.path(path_proj(), "man"), showWarnings = FALSE) + # dir.create(file.path(path_proj(), "man"), showWarnings = FALSE) - if (!quiet) ui_done("Creating {ui_value('man/')} directory") + # if (!quiet) ui_done("Creating {ui_value('man/')} directory") if (!quiet) ui_line() @@ -448,7 +446,7 @@ new_compendium <- function(compendium = ".", license = "GPL (>= 2)", if (!quiet) ui_line() if (!quiet) ui_done("Writing {ui_value('R/fun-demo.R')} file") - suppressMessages(devtools::document(quiet = TRUE)) + # suppressMessages(devtools::document(quiet = TRUE)) add_to_gitignore("man/", quiet = quiet) add_to_gitignore("NAMESPACE", quiet = quiet) @@ -462,7 +460,7 @@ new_compendium <- function(compendium = ".", license = "GPL (>= 2)", ui_title("Creating Compendium Folders") - add_compendium(compendium) + add_compendium(compendium, quiet = quiet) ui_line() add_makefile(given, family, email, open = FALSE, overwrite = overwrite, @@ -799,13 +797,21 @@ new_compendium <- function(compendium = ".", license = "GPL (>= 2)", if (test) ui_todo(paste0("Write your units tests in the ", "{ui_value('tests/testthat/')} directory")) + + if (!is.null(compendium)) { + + ui_line() + ui_todo("Put your data in {ui_value('data/raw-data')} directory") + ui_todo("Write your R scripts in the {ui_value('analyses/')} directory") + ui_todo("Source your R scripts in the {ui_value('make.R')} file") + ui_todo(paste0("Export your derived data in the ", + "{ui_value('data/derived-data/')} directory")) + ui_todo("Export your outputs in the {ui_value('outputs/')} directory") + ui_todo("Export your figures in the {ui_value('figures/')} directory") + } + ui_line() - ui_todo("Put your data in {ui_value('data/')} directory") - ui_todo("Write your R scripts in the {ui_value('analyses/')} directory") - ui_todo("Export your outputs in the {ui_value('outputs/')} directory") - ui_todo("Export your figures in the {ui_value('figures/')} directory") - ui_line() - ui_todo("Refresh your package with {ui_code('refresh()')}") + ui_todo("...and commit your changes!") invisible(NULL) diff --git a/man/add_compendium.Rd b/man/add_compendium.Rd index 6726792..8d68eea 100644 --- a/man/add_compendium.Rd +++ b/man/add_compendium.Rd @@ -2,29 +2,32 @@ % Please edit documentation in R/add_compendium.R \name{add_compendium} \alias{add_compendium} -\title{Create compendium folders} +\title{Create additional folders} \usage{ -add_compendium(compendium = ".") +add_compendium(compendium = NULL, quiet = FALSE) } \arguments{ -\item{compendium}{A character of length 1. By default, compendium folders -are created at the root of the project. User can change their location -with this argument. For instance, if \code{compendium = 'analysis'}, compendium -folders will be created inside the directory \verb{analysis/}.} +\item{compendium}{A character vector specifying the folders to be created.} + +\item{quiet}{A logical value. If \code{TRUE} messages are deleted. Default is +\code{FALSE}.} } \value{ No return value. } \description{ -This function creates the following additional folders \verb{data/}, \verb{analyses/}, -\verb{outputs/}, and \verb{figures/}. Each folder has a \code{README.md} to provide -instructions. The argument \code{compendium} allows user to choose if these -folders are created at the root of the project (default) or nested inside a -parent directory. All theses folders are added to the \code{.Rbuildignore} file. +This function creates a compendium, i.e. additional folders to a package +structure. By default, the following directories are created: +\code{data/raw-data}, \code{data/derived-data}, \verb{analyses/}, \verb{outputs/}, and +\verb{figures/}. A \code{README.md} is added to each folder and must be edited. The +argument \code{compendium} allows user to choose its own compendium structure. +All theses folders are added to the \code{.Rbuildignore} file. } \examples{ \dontrun{ add_compendium() +add_compendium(compendium = "paper") +add_compendium(compendium = c("data", "outputs", "code", "manuscript")) } } \seealso{ diff --git a/man/new_compendium.Rd b/man/new_compendium.Rd index 4cdc0f4..65a9dfc 100644 --- a/man/new_compendium.Rd +++ b/man/new_compendium.Rd @@ -5,7 +5,7 @@ \title{Create an R compendium structure} \usage{ new_compendium( - compendium = ".", + compendium = NULL, license = "GPL (>= 2)", status = NULL, lifecycle = NULL, @@ -29,10 +29,8 @@ new_compendium( ) } \arguments{ -\item{compendium}{A character vector of length 1. By default, compendium -folders are created at the root of the project. User can change their -location with this argument. For instance, if \code{compendium = 'analysis'}, -compendium folders will be created inside the directory \verb{analysis/}.} +\item{compendium}{A character vector specifying the folders to be created. +See \code{\link[=add_compendium]{add_compendium()}} for further information.} \item{license}{A character vector of length 1. The license to be used for this project. Run \code{\link[=get_licenses]{get_licenses()}} to choose an appropriate one. Default