Support `@examplesIf` tag in `roxygen2`

[vincentarelbundock]

The roxygen2 package supports an @examplesIf tag. Next to that tag, users include R code that gets evaluated to TRUE or FALSE, which determines if the examples get evaluated.

When the documentation is rendered, roxygen2 adds a weird long string (see below). This is done here.

This PR uses ugly/hacky regexes to extract the code to be evaluated form the .Rd file, run it, and decide if we should eval the code examples. The main problem with this approach is that if roxygen2 changes the string, we'll need to update altdoc so that the regex works again.

What do you all think?

For reference, the roxygen2 code looks like this:

#' @export
#' @examplesIf on_workbench()
#'
... example code ...
#'

.Rd file looks like this:

\examples{
\dontshow{if (on_workbench()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}

... example code ...

\dontshow{\}) # examplesIf}
}

[vincentarelbundock]

FWIW, the specific string that we are using to detect @examplesIf has been in roxygen2 for 4 years. It's probably reasonably safe to use, even if it feels like a hack.

[vincentarelbundock]

Can you also add two expect_snapshot() for those files in test-render_docs.R?

I don't know how to. I tried adding the two lines in that file, but when I run testthat::test_file() the new snapshots are not created.

[etiennebacher]

I updated them.

You should need to run the tests once so that there are new snapshot files (should appear in git diff) and then run testthat::snapshot_accept() to accept them (or testthat::snapshot_review()). It's a bit easier in RStudio because there is clickable text to automatically accept the snapshots after tests are run in "Build" pane.

I didn't add them in the mkdocs variant because the tool used shouldn't matter here and I have trouble with mkdocs in the test suite

[etiennebacher]

Feel free to merge if you're happy with that, I don't have more comments

[vincentarelbundock]

Cool. FYI, I don't plan to make more changes to this, unless you make more requests. So don't wait on me to merge if you think it's fine.

[vincentarelbundock]

Haha, ok, we posted at the same time