document package options

R/DataPackageR-package.R

@@ -86,3 +86,37 @@
 ## usethis namespace: start
 ## usethis namespace: end
 NULL
+
+#' Options consulted by DataPackageR
+#'
+#' @description User-configurable options consulted by DataPackageR, which
+#'   provide a mechanism for setting default behaviors for various functions.
+#'
+#'   If the built-in defaults don't suit you, set one or more of these options.
+#'   Typically, this is done in the \code{.Rprofile} startup file, which you can open
+#'   for editing with \code{usethis::edit_r_profile()} - this will set the specified
+#'   options for all future R sessions. The following setting is recommended to
+#'   not be prompted upon each package build for a NEWS update:
+#'
+#' \code{options(DataPackageR_interact = FALSE)}
+#'
+#' @section Options for the DataPackageR package:
+#'
+#' - \code{DataPackageR_interact}: Upon package load, this defaults to the value of
+#'   \code{interactive()}, unless the option has been previously set (e.g., in
+#'   \code{.Rprofile}). TRUE prompts user interactively for a NEWS update on
+#'   \code{package_build()}. See the example above and the [rOpenSci blog
+#'   post](https://ropensci.org/blog/2018/09/18/datapackager/) for more details
+#'   on how to set this to FALSE, which will never prompt user for a NEWS
+#'   update. FALSE is also the setting used for DataPackageR's internal tests.
+#'
+#' - \code{DataPackageR_verbose}: Default upon package load is TRUE. FALSE suppresses
+#'   all console output and is currently only used for DataPackageR's automated
+#'   unit tests.
+#'
+#' - \code{DataPackageR_packagebuilding}: Default upon package load is FALSE. This
+#'   option is used internally for package operations and changing it is not
+#'   recommended.
+#'
+#' @name DataPackageR_options
+NULL