In gaborcsardi/dynex: Dynamic Manual Page Examples with Roxygen

knitr::opts_chunk$set(
  comment = "#>",
  tidy = FALSE,
  error = FALSE,
  fig.width = 8,
  fig.height = 8)

dynex

Dynamic examples with roxygen

Minimal roxygen2 extension that defines the @dynex tag, to create manual page examples that only run (via utils::example() and during R CMD check), if a certain condition holds.

Some potential use cases:

• Avoid failures if the computer if offline.
• Avoid failures if a package is not installed.
• Avoid long running examples on CRAN.

Note that this package is currently experimental.

Installation

install.packages("dynex")

Usage

1. Use the @dynex tag in your roxygen blocks to create dynamic examples. The first line of each example should contain the condition for the example code to run, e.g. to run it in interactive sessions, you would add #' @dynex #' interactive() #' name <- readline("name> ") #' cat("hello", name) Or if you need internet connection: #' @dynex #' pingr::is_online() #' # This example needs internet connection #' pingr::nsl("www.r-project.org")
2. Load the dynex package.
3. Call devtools::document() or roxygen2::roxygenize() on your package.

The @dynex tags will create the following Rd code:

\examples{
\dontshow{ if (interactive()) \{ }
name <- readline("name> ")
cat("hello", name)\dontshow{ \} }
\dontshow{ if (pingr::is_online()) \{ }
# This example needs internet connection
pingr::nsl("www.r-project.org")\dontshow{ \} }
}

Roxygen2 adds the check for the condition in \dontshow{} tags, so users looking at the manual page will not get distracted by the boilerplate when they look at the rendered manual page:

Examples:

     name <- readline("name> ")
     cat('hello', name)

     # This example needs internet connection
     pingr::nsl("www.r-project.org")

License

MIT © RStudio

gaborcsardi/dynex documentation built on Nov. 14, 2019, 2:52 p.m.