rocleteer

A roxygen2 extension collection package.

Installation

You can install the development version of {rocleteer} from GitHub:

# install.packages("devtools")
devtools::install_github("coatless-rpkg/rocleteer")

Usage

In your package’s DESCRIPTION file, add {rocleteer} to your Suggests, coatless-rpkg/rocleteer to your Remotes, and include rocletter in your Roxygen list of packages.

Suggests:
    rocleteer

Remotes:
  coatless-rpkg/rocleteer

Roxygen: list(..., packages = c("rocleteer"))

where ... could be roclets = c("collate", "namespace", "rd").

@examplesTempdir

When writing examples for R package functions, you often need to create temporary files or directories. To avoid cluttering the user’s workspace, it’s good practice to use a temporary directory for these examples.

Traditionally, you would need to manually set up and switch out of the temporary directory like this:

#' @examples
#' \dontshow{.old_wd <- setwd(tempdir())}
#'
#' # Your code here
#'
#' \dontshow{setwd(.old_wd)}

With {rocleteer}, you can simply use the @examplesTempdir tag instead:

#' @examplesTempdir
#' # Your code here

The @examplesTempdir tag handles this automatically. So, if you have a function like this:

#' Example function
#'
#' @examplesTempdir
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' @export
example_function <- function() {
  # Function implementation
}

The documentation will be processed by roxygen2 as:

#' Example function
#'
#' @examples
#' \dontshow{
#' .old_wd <- setwd(tempdir()) # examplesTempdir
#' }
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' \dontshow{
#' setwd(.old_wd) # examplesTempdir
#' }
#'
#' @export
example_function <- function() {
  # Function implementation
}

Note

This roclet is inspired by an old post of mine that I initially shared in 2018 covering this pattern.

License

AGPL (>=3)