Accessing test helpers from within documentation files.

[arangaca]

I've a bunch of helper functions for testing that are located in tests/testthat/helper.R. I'd like to reuse some of these helpers to build examples in the pkgdown documentation. Unfortunately I can't access them with pkg:::fun whether I place them under the testthat/ or R/ directory.

Is there any way to access these helpers from within the vignettes/README without exporting them publicly or redeclaring them at the top of each file?

[jdblischak]

What are these helpers functions used for? Are they primarily creating/preparing data sets to be used by your package functions? If yes, have you considered saving the prepared data objects as exported data sets in your package? This would make it easy to reuse the data objects in your examples and vignettes (and also make it easy for your users to try your package functions).

[arangaca]

To give some context, I'm wrapping up a tiny package that references and cites R packages on the fly in Quarto/R Markdown. The package contains a single function that is intended to be used in a rendering context only (it's technically possible to run the function in a different context but the output would be quite useless).

The helpers set up temporary files/directory and render R Markdown documents locally, which is also what I need to do to make the examples.

This is a draft but here're the helpers:

template <- "
  ---
  title: test
  bibliography: %s
  ---

  ```{r include = FALSE}
  library(foo)
  ```

  %s

  ## References
"

dedent <- function(x) {
  indentation <- sub("(?s)\\S*\n(\\s*).+", "\\1", x, perl = TRUE)
  x <- gsub(paste0("(?m)^", indentation), "", x, perl = TRUE)
  trimws(x)
}

render <- function(...) {
  rmarkdown::render(..., output_format = "md_document", quiet = TRUE)
}


local_rmd <- function(lines, ...) {
  withr::local_tempfile(lines = lines, fileext = ".Rmd", ...)
}

local_bib <- function(lines, ...) {
  withr::local_tempfile(
    lines = if (missing(lines)) "" else lines,
    fileext = ".bib",
    ...
  )
}

get_template <- function(bib, lines) {
  sprintf(dedent(template), bib, lines)
}

local_files <- function(rmd_lines, bib_lines, env = parent.frame()) {
  dir <- withr::local_tempdir(.local_envir = env)
  bib <- local_bib(bib_lines, tmpdir = dir, .local_envir = env)
  template <- get_template(bib, rmd_lines)
  rmd <- local_rmd(template, tmpdir = dir, .local_envir = env)
  list(dir = dir, rmd = rmd)
}

read_local_file <- function(dir, ext = "md") {
  file <- list.files(dir, pattern = sprintf("\\.%s$", ext), full.names = TRUE)
  readr::read_file(file)
}

as_inline_chunk <- function(...) {
  paste(sprintf("`r %s`", c(...)), collapse = "\n\n")
}

local_output <- function(..., bib_lines, ext = "md") {
  items <- local_files(as_inline_chunk(...), bib_lines)
  callr::r(render, list(input = items$rmd))
  read_local_file(items$dir, ext = ext)
}

As you can see, this isn't very portable… and I'm not too keen on exporting local_output() (the function that would generate the examples).

[Gabor]

What do you mean by "generating examples"? During a devtools::document() run? Or when the user runs the examples? Or during package installation?

In any case, probably the simplest thing to do is to put those functions into the package, i.e. into /R instead of into the test helpers.

[jdblischak]

@arangaca

Unfortunately I can't access them with pkg:::fun whether I place them under the testthat/ or R/ directory.

You should try putting them under R/ again. Any function defined in a file within R/ should be accessible via :::

[arangaca]

@jdblischak

Any function defined in a file within R/ should be accessible via :::

I tried it in R Studio and it's now working. I use both VS Code and R Studio and was wrongly expecting them to behave the same… R Studio restarts the session after installing the package, not VS Code. I kept installing the package without success when I simply needed to reopen VS Code…

@Gabor

What do you mean by "generating examples"? During a devtools::document() run? Or when the user runs the examples? Or during package installation?

Sorry that wasn't clear. I simply meant to produce the output that I could use as examples in the README file or introductory vignettes on the pkgdown site.