feat: allow user to choose the compendium structure - fix #50

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()`

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)

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)