createDESCRIPTIONandDocs: Convert standard module code into an R package

In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

Convert standard module code into an R package

Description

EXPERIMENTAL – USE WITH CAUTION. This function will create a DESCRIPTION file if one does not exist, based on the module metadata. If one exists, it will update it with any additional information: it will not remove packages that are removed from the metadata. It will create, if one does not exist, or update a .Rbuildignore file. If importAll = TRUE It will create a file named R/imports.R, which will import all functions. This function will make no changes to any existing source file of a SpaDES.module. If buildDocumentation = TRUE, it will build documentation .Rd files from roxygen2 tags.

Usage

createDESCRIPTIONandDocs(
  module = NULL,
  path = getOption("spades.modulePath"),
  importAll = TRUE,
  buildDocuments = TRUE,
  verbose = getOption("Require.verbose")
)

Arguments

module	Character string of module name, without path
path	Character string of modulePath. Defaults to getOption("spades.modulePath").
importAll	A logical. If TRUE, then every package named in reqdPkgs will have an ⁠@importFrom <pkgName>⁠, meaning every function from every package will be imported. If FALSE, then only functions explicitly imported using ⁠@importFrom <pkgName> <functionName>⁠ will be imported.
buildDocuments	A logical. If TRUE, the default, then the documentation will be built, if any exists, using roxygen2::roxygenise.
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠

Details

This function does not install anything (e.g., devtools::install). After running this function, simInit will automatically detect that this is now a package and will load the functions (via pkgload::load_all) from the source files. This will have the effect that it emulates the "non-package" behaviour of a SpaDES module exactly. After running this function, current tests show no impact on module behaviour, other than event-level and module-level Caching will show changes and will be rerun. Function-level Caching appears unaffected. In other words, this should cause no changes to running the module code via simInit and spades.

This function will create and fill a minimal DESCRIPTION file. This will leave the defineModule function call as the only code in the main module file. This defineModule and a doEvent.xxx are the only 2 elements that are required for an R package to be considered a SpaDES module. With these changes, the module should still function normally, but will be able to act like an R package, e.g., for writing function documentation with roxygen2, using the testthat infrastructure, etc.

This function is intended to be run once for a module that was created using the "standard" SpaDES module structure (e.g., from a newModule call). There is currently no way to "revert" the changes from R (though it can be done using version control utilities if all files are under version control, e.g., GitHub). Currently SpaDES.core identifies a module as being a package if it has a DESCRIPTION file, or if it has been installed to the .libPaths() e.g., via devtools::install or the like. So one can simply remove the package from .libPaths and delete the DESCRIPTION file and SpaDES.core will treat it as a normal module.

Value

Invoked for its side effects. There will be a new or modified DESCRIPTION file in the root directory of the module. Any functions that were in the main module script (i.e., the .R file whose filename is the name of the module and is in the root directory of the module) will be moved to individual .R files in the R folder. Any function with a dot prefix will have the dot removed in its respective filename, but the function name is unaffected.

Currently, SpaDES.core does not install the package under any circumstances. It will load it via pkgdown::load_all, and optionally (option("spades.moduleDocument" = TRUE)) build documentation via roxygen2::roxygenise within the simInit call. This means that any modifications to source code will be read in during the simInit call, as is the practice when a module is not a package.

invoked for the side effect of creating DESCRIPTION file, a .Rbuildingore file and possibly building documentation from roxygen2 tags.

Reverting

Currently, this is not a reversible process. We recommend trying one module at a time, running your code. If all seems to work, then great. Commit the changes. If things don't seem to work, then revert the changes and continue on as before. Ideally, file a bug report on the SpaDES.core GitHub.com pages.

Currently

Exported functions

The only function that will be exported by default is the doEvent.xxx, where xxx is the module name. If any other module is to be exported, it must be explicitly exported with e.g., ⁠@export⁠, and then building the NAMESPACE file, e.g., via devtools::document(moduleRootPath). NOTE: as long as all the functions are being used inside each other, and they all can be traced back to a call in doEvent.xxx, then there is no need to export anything else.

DESCRIPTION

The DESCRIPTION file that is created (destroying any existing DESCRIPTION file) with this function will have several elements that a user may wish to change. Notably, all packages that were in reqdPkgs in the SpaDES module metadata will be in the Imports section of the DESCRIPTION. To accommodate the need to see these functions, a new R script, imports.R will be created with ⁠@import⁠ for each package in reqdPkgs of the module metadata. However, if a module already has used ⁠@importFrom⁠ for importing a function from a package, then the generic ⁠@import⁠ will be omitted for that (those) package(s). So, a user should likely follow standard R package best practices and use ⁠@importFrom⁠ to identify the specific functions that are required within external packages, thereby limiting function name collisions (and the warnings that come with them).

Other elements of a standard DESCRIPTION file that will be missing or possibly inappropriately short are Title, Description, URL, BugReports.

Installing as a package

There is no need to "install" the source code as a package because simInit will load it on the fly. But, there may be reasons to install it, e.g., to have access to individual functions, help manual, running tests etc. To do this, simply use the devtools::install(pathToModuleRoot). Even if it is installed, simInit will nevertheless run pkgload::load_all to ensure the spades call will be using the current source code.

Examples

if (requireNamespace("ggplot2") && requireNamespace("pkgload") ) {
  tmpdir <- tempdir2()
  newModule("test", tmpdir, open = FALSE)
  createDESCRIPTIONandDocs("test", path = tmpdir)
}

SpaDES.core documentation built on Jan. 11, 2026, 9:06 a.m.