Rename to create_turing and add doc

Because `use_` function assumes the dir. exists

NAMESPACE

@@ -10,6 +10,7 @@ S3method(print,rang)
 S3method(print,ranglet)
 export(as_pkgrefs)
 export(convert_edgelist)
+export(create_turing)
 export(dockerise)
 export(dockerise_rang)
 export(dockerize)

R/use_rang.R

@@ -1,6 +1,6 @@
 #' Setup rang for a directory
 #'
-#' This function adds the infrastructure in a directory (presumably with R scripts
+#' This `usethis`-style function adds the infrastructure in a directory (presumably with R scripts
 #' and data) for (re)constructing the computational environment.
 #' Specifically, this function inserts `inst/rang` into the directory, which contains
 #' all components for the reconstruction. Optionally, `Makefile` and `.here` are also inserted
@@ -53,13 +53,41 @@ use_rang <- function(path = ".", add_makefile = TRUE, add_here = TRUE,
     return(invisible(path))
 }
 
-use_turing <- function(path, add_rang = TRUE, ...) {
+#' Create executable research compendium according to the Turing Way
+#'
+#' This `usethis`-style function creates an executable research compendium according to the Turing Way.
+#' @param path character, path to the project root
+#' @param add_rang logical, whether to run [use_rang()] to `path`
+#' @param ... additional parameters pass to [use_rang()]
+#' @return path, invisibly
+#' @seealso [use_rang()]
+#' @details
+#' A research compendium according to the Turing Way contains:
+#' * `data_raw`: a directory to hold the raw data
+#' * `data_clean`: a directory to hold the processed data
+#' * `code`: a directory to hold computer code
+#' * `CITATION`: a file holding citation information
+#' * `paper.Rmd`: a manuscript
+#' The structure is just a suggestion. For example, the manuscript can be in other format.
+#'
+#' According to the Turing Way, an executable research compendium should
+#' 1. Files should be organized in a conventional folder structure;
+#' 2. Data, methods, and output should be clearly separated;
+#' 3. The computational environment should be specified.
+#'
+#' With `add_rang`, the computational environment can be recorded and reconstructed later.
+#' @references
+#' [The Turing Way: Research Compendia](https://the-turing-way.netlify.app/reproducible-research/compendia.html)
+#' Gorman, KB, Williams TD. and Fraser WR (2014). [Ecological Sexual Dimorphism and Environmental Variability within a Community of Antarctic Penguins (Genus Pygoscelis)](http://dx.doi.org/10.1371/journal.pone.0090081). PLoS ONE 9(3):e90081.
+#' @export
+create_turing <- function(path, add_rang = TRUE, ...) {
     if (isTRUE(dir.exists(path))) {
         stop("`path` exists.")
     }
     dir.create(path)
     file.copy(from = list.files(system.file("turing", package = "rang"), full.names = TRUE),
               to = path, recursive = TRUE)
+    writeLines(c("Please cite this research compendium as:", "", "    <CITATION INFORMATION HERE>"), file.path(path, "CITATION"))
     dir.create(file.path(path, "figures"))
     dir.create(file.path(path, "data_clean"))
     if (isTRUE(add_rang)) {

tests/testthat/test_use_turing.R → tests/testthat/test_create_turing.R

@@ -2,31 +2,32 @@
     file.path(tempdir(), paste(sample(c(LETTERS, letters), 20, replace = TRUE), collapse = ""))
 }
 
-test_that("use_turing defensive", {
+test_that("create_turing defensive", {
     existing_dir <- .generate_temp_dir()
     dir.create(existing_dir)
-    expect_error(use_turing(existing_dir))
+    expect_error(create_turing(existing_dir))
 })
 
-test_that("use_turing all cases", {
+test_that("create_turing all cases", {
     temp_dir <- .generate_temp_dir()
-    use_turing(temp_dir, verbose = FALSE) ## add_rang = TRUE
+    create_turing(temp_dir, verbose = FALSE) ## add_rang = TRUE
     expect_true(dir.exists(temp_dir))
+    expect_true(file.exists(file.path(temp_dir, "CITATION")))
     expect_true(dir.exists(file.path(temp_dir, "data_raw")))
     expect_true(dir.exists(file.path(temp_dir, "data_clean")))
     expect_true(dir.exists(file.path(temp_dir, "figures")))
     expect_true(file.exists(file.path(temp_dir, "Makefile")))
     expect_true(dir.exists(file.path(temp_dir, "inst/rang")))
     temp_dir <- .generate_temp_dir()
-    use_turing(temp_dir, verbose = FALSE, add_makefile = FALSE) ## add_rang = TRUE
+    create_turing(temp_dir, verbose = FALSE, add_makefile = FALSE) ## add_rang = TRUE
     expect_false(file.exists(file.path(temp_dir, "Makefile")))
     expect_true(dir.exists(temp_dir))
     expect_true(dir.exists(file.path(temp_dir, "data_raw")))
     expect_true(dir.exists(file.path(temp_dir, "data_clean")))
     expect_true(dir.exists(file.path(temp_dir, "figures")))
     expect_true(dir.exists(file.path(temp_dir, "inst/rang")))
     temp_dir <- .generate_temp_dir()
-    use_turing(temp_dir, add_rang = FALSE)
+    create_turing(temp_dir, add_rang = FALSE)
     expect_true(dir.exists(temp_dir))
     expect_true(dir.exists(file.path(temp_dir, "data_raw")))
     expect_true(dir.exists(file.path(temp_dir, "data_clean")))