Dynamic examples

[gaborcsardi]

The current practice of writing conditional examples, i.e. examples that need a certain package to be installed, a certain platform, etc., is not ideal, because we need to include the boilerplate code that checks for the suitable conditions in the body of the example itself.

With an R CMD check issue fixed recently (wch/r-source@1501a3e), we are able to generate the \examples block dynamically, at install time, or potentially even at runtime.

We need to produce the following Rd:

\Sexpr[stage=install,strip.white=FALSE,results=rd]{roxygen2::dynamic_example(condition, '
<R code>
')}

stage will need to be render in some cases, e.g. when checking for the presence of a package, that has to happen at run time.

This also means that roxygen2 will be a dependency of these packages. Alternatively it will generate some code that the package author needs to put in the package. Neither are very good solutions...

The API in roxygen could be something like this:

#' @examplesIf ps::ps_is_supported() ## ps does not support this platform :(
<R code>

and if ps::ps_is_supported() is TRUE, thenroxygen2::dynamic_example() will generate the normal \examples block with <R code>. Otherwise it would generate this:

\examples{
## ps does not support this platform :(
\dontrun{
<R code>
}
}

We'll still need

• Some way to specify whether to run ps::ps_is_supported() at install time or render time.
• Some way to specify multi-line comments. Maybe ps::ps_is_supported() should just return the comments to be inserted into the docs for a negative answer, and TRUE otherwise?
• Shorthand for checking if a package is available.
• Shorthand for checking for platform(s).

[hadley]

Do you think this strategy is still viable now that CRAN is requiring that most (all?) documentation files have executable examples?

[gaborcsardi]

I think so, yes. I think the most common case is that a package is needed to run the example. This package is probably suggested, so it is installed for the check, and a proper example is generated dynamically.

Even if the example does not work for a CRAN check, we'll dynamically generate a placeholder instead, and this might also work as an "example" for the automatic checks.

The human review is a tossup, I guess. But usually there is no human review for package updates, so in practice I think we are fine, even if CRAN is not enthusiastic about the dynamic examples.

My only worry is that the package must be installed for R CMD build which is quite annoying. Ideally we would fix base R not to do that if all \Sexpr run
at the install/render stage.

[krlmlr]

Instead of adding a roxygen2 dependency, maybe roxygen2 could add a helper file à la compat-purrr.R ?

[gaborcsardi]

Instead of adding a roxygen2 dependency, maybe roxygen2 could add a helper file à la compat-purrr.R ?

Yeah, that's an option. Roxygen does not generate files in R/ currently, though, so it is a new thing.

[gaborcsardi]

There is a proof of concept here: https://github.com/gaborcsardi/dynex

The main problem is that this still generates an R CMD check warning, because of the top-level \Sexpr{} Rd section. Rd does not let us embed \Sexpr{} into \examples{}, however, so this is probably the end of the story.

W  checking whether package 'dynex' can be installed
   Found the following significant warnings:
     Warning: C:/Users/USERvQPRTUnCBy/dynex.Rcheck/00_pkg_src/dynex/man/dynex-test.Rd:10-15: Section \Sexpr is unrecognized and will be dropped
   See 'C:/Users/USERvQPRTUnCBy/dynex.Rcheck/00install.out' for details.

[gaborcsardi]

The installation warning seems to be a similar bug to https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17479, I reported it at https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17623#c0