From b71c614ea7fba7f077e52d4133df4659577efd1a Mon Sep 17 00:00:00 2001 From: Francisco Cardozo Date: Thu, 22 Aug 2024 17:19:25 -0400 Subject: [PATCH 1/3] Add a funtion, NAMESPACE and man --- NAMESPACE | 1 + R/use_document_data.R | 98 ++++++++++++++++++++++++++++++++++ man/create_data_description.Rd | 29 ++++++++++ man/use_document_data.Rd | 40 ++++++++++++++ 4 files changed, 168 insertions(+) create mode 100644 R/use_document_data.R create mode 100644 man/create_data_description.Rd create mode 100644 man/use_document_data.Rd diff --git a/NAMESPACE b/NAMESPACE index 0a1e4ae87..bc3230aa1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -115,6 +115,7 @@ export(use_dev_package) export(use_dev_version) export(use_devtools) export(use_directory) +export(use_document_data) export(use_git) export(use_git_config) export(use_git_hook) diff --git a/R/use_document_data.R b/R/use_document_data.R new file mode 100644 index 000000000..747764d6c --- /dev/null +++ b/R/use_document_data.R @@ -0,0 +1,98 @@ +#' Document Data +#' +#' @description +#' `use_document_data()` creates an .R file containing detailed documentation +#' of a provided data set. It automatically generates a roxygen template including +#' variables' names, data types, row and column counts, and placeholders for further description. +#' +#' @param .data A data set loaded in the R environment. The function extracts its +#' name, type, class, dimensions, and column names for documentation. +#' @param path The directory where the documentation file will be saved. Defaults to the current working directory. +#' @param overwrite Logical, whether to overwrite an existing file with the same name. Defaults to `FALSE`. +#' @param description A character string for the data set description. Defaults to "Describe your data set here". +#' @param source A character string indicating the source of the data set. Defaults to "Add your source here". +#' +#' @return Invisibly returns the file path where the documentation was saved. +#' +#' @export +#' @examples +#' \dontrun{ +#' the_data <- as.data.frame(datasets::Titanic) +#' use_document_data(the_data) +#' } +use_document_data <- function(.data, path = ".", overwrite = FALSE, + description = "Describe your dataset here", + source = "Add your source here") { + dataset_name <- rlang::as_name(rlang::enquo(.data)) + + if (!inherits(.data, "data.frame")) { + ui_abort("The provided object is not a data frame.") + } + + file_path <- fs::path(path, paste0(dataset_name, ".R")) + + if (fs::file_exists(file_path) && !overwrite) { + ui_abort(paste0("File '", file_path, "' already exists. Use `overwrite = TRUE` to overwrite it.")) + } + + data_description <- create_data_description(.data, dataset_name, description, source) + cat(data_description, file = file_path) + + ui_bullets(c( + "*" = paste0("Documentation file created: ", pth(file_path), "."), + "_" = "Finish writing the data documentation in the generated file." + )) + + invisible(file_path) +} + +#' Create Data Description +#' +#' @description +#' Generates a description of a data set, including information about +#' its type, class, dimensions (rows and columns), and a placeholder for each +#' variable's description. This description is formatted as a string that could +#' be used directly in R documentation files or other descriptive materials. +#' +#' @param dataset A data frame for which the description is to be generated. +#' @param name The name of the data set, which will be used in the title and usage +#' sections of the generated description. +#' @param description A character string for the data set description. +#' @param source A character string indicating the source of the data set. +#' +#' @return A character string containing the structured documentation template +#' for the data set. This includes the data set's basic information and +#' placeholders for detailed descriptions of each variable. +#' +#' +create_data_description <- function(dataset, name, description, source) { + data_info <- generate_data_info(dataset) + variable_descriptions <- generate_variable_descriptions(dataset) + + description_template <- paste0( + "#' @title ", name, "\n", + "#' @description ", description, "\n", + "#' @docType data\n", + "#' @usage data(", name, ")\n", + "#' @format ", data_info, + "#' \\itemize{\n", + "#' ", paste(variable_descriptions, collapse = "\n#' "), "\n#' }\n", + "#' @source ", source, "\n", + "'", name, "'" + ) + + return(description_template) +} + +generate_data_info <- function(dataset) { + paste0( + "A ", typeof(dataset), " [", class(dataset), "] with ", + nrow(dataset), " rows and ", length(names(dataset)), " variables:\n" + ) +} + +generate_variable_descriptions <- function(dataset) { + purrr::map_chr(names(dataset), function(var) { + paste0("\\item{", var, "} {", class(dataset[[var]]), ": Type label here}") + }) +} diff --git a/man/create_data_description.Rd b/man/create_data_description.Rd new file mode 100644 index 000000000..c0e95fff3 --- /dev/null +++ b/man/create_data_description.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_document_data.R +\name{create_data_description} +\alias{create_data_description} +\title{Create Data Description} +\usage{ +create_data_description(dataset, name, description, source) +} +\arguments{ +\item{dataset}{A data frame for which the description is to be generated.} + +\item{name}{The name of the data set, which will be used in the title and usage +sections of the generated description.} + +\item{description}{A character string for the data set description.} + +\item{source}{A character string indicating the source of the data set.} +} +\value{ +A character string containing the structured documentation template +for the data set. This includes the data set's basic information and +placeholders for detailed descriptions of each variable. +} +\description{ +Generates a description of a data set, including information about +its type, class, dimensions (rows and columns), and a placeholder for each +variable's description. This description is formatted as a string that could +be used directly in R documentation files or other descriptive materials. +} diff --git a/man/use_document_data.Rd b/man/use_document_data.Rd new file mode 100644 index 000000000..43e46b163 --- /dev/null +++ b/man/use_document_data.Rd @@ -0,0 +1,40 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_document_data.R +\name{use_document_data} +\alias{use_document_data} +\title{Document Data} +\usage{ +use_document_data( + .data, + path = ".", + overwrite = FALSE, + description = "Describe your dataset here", + source = "Add your source here" +) +} +\arguments{ +\item{.data}{A data set loaded in the R environment. The function extracts its +name, type, class, dimensions, and column names for documentation.} + +\item{path}{The directory where the documentation file will be saved. Defaults to the current working directory.} + +\item{overwrite}{Logical, whether to overwrite an existing file with the same name. Defaults to \code{FALSE}.} + +\item{description}{A character string for the data set description. Defaults to "Describe your data set here".} + +\item{source}{A character string indicating the source of the data set. Defaults to "Add your source here".} +} +\value{ +Invisibly returns the file path where the documentation was saved. +} +\description{ +\code{use_document_data()} creates an .R file containing detailed documentation +of a provided data set. It automatically generates a roxygen template including +variables' names, data types, row and column counts, and placeholders for further description. +} +\examples{ +\dontrun{ +the_data <- as.data.frame(datasets::Titanic) +use_document_data(the_data) +} +} From c85353afb10c722aec35648d3dc043a7488599d9 Mon Sep 17 00:00:00 2001 From: Francisco Cardozo Date: Sat, 24 Aug 2024 15:15:05 -0400 Subject: [PATCH 2/3] Add @keywords internal to `create_data_description` --- R/use_document_data.R | 1 + man/create_data_description.Rd | 1 + 2 files changed, 2 insertions(+) diff --git a/R/use_document_data.R b/R/use_document_data.R index 747764d6c..26df5fe0d 100644 --- a/R/use_document_data.R +++ b/R/use_document_data.R @@ -64,6 +64,7 @@ use_document_data <- function(.data, path = ".", overwrite = FALSE, #' for the data set. This includes the data set's basic information and #' placeholders for detailed descriptions of each variable. #' +#' @keywords internal #' create_data_description <- function(dataset, name, description, source) { data_info <- generate_data_info(dataset) diff --git a/man/create_data_description.Rd b/man/create_data_description.Rd index c0e95fff3..51caf5155 100644 --- a/man/create_data_description.Rd +++ b/man/create_data_description.Rd @@ -27,3 +27,4 @@ its type, class, dimensions (rows and columns), and a placeholder for each variable's description. This description is formatted as a string that could be used directly in R documentation files or other descriptive materials. } +\keyword{internal} From 437be71b89d1cbe878c12b76baf8c6c4318ba271 Mon Sep 17 00:00:00 2001 From: Francisco Cardozo Date: Sat, 24 Aug 2024 15:25:30 -0400 Subject: [PATCH 3/3] Add use_document_data to reference index --- _pkgdown.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/_pkgdown.yml b/_pkgdown.yml index df4d8a5e7..cf7c51317 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -64,6 +64,7 @@ reference: - use_citation - use_tutorial - use_author + - use_document_data - title: Package setup desc: > Package setup tasks, typically performed once.