-
Notifications
You must be signed in to change notification settings - Fork 5
Description
The @examples
in endpoint documentation are usually guarded with \dontrun
, lest CRAN try to run all of the examples as part of R CMD check
and hit the API query limit. But this means that the examples do not run when building the pkgdown site, and hence the documentation site doesn't have examples showing the output of requests. The output would be very useful to show so readers understand what kind of data (and in what format) they get from requests.
We should investigate whether \donttest
is acceptable instead. According to the manual,
Finally, there is
\donttest
, used (at the beginning of a separate line) to mark code that should be run byexample()
but not byR CMD check
(by default: the option--run-donttest
can be used). This should be needed only occasionally but can be used for code which might fail in circumstances that are hard to test for, for example in some locales. (Use e.g.capabilities()
ornzchar(Sys.which("someprogram"))
to test for features needed in the examples wherever possible, and you can also usetry()
ortryCatch()
. Useinteractive()
to condition examples which need someone to interact with.) Note that code included in\donttest
must be correct R code, and any packages used should be declared in theDESCRIPTION
file. It is good practice to include a comment in the\donttest
section explaining why it is needed.
I presume this means pkgdown would render the examples, but CRAN would not complain if they produce API query warnings. I'm not sure if CRAN would run the examples at all in this case, or merely run them in some context that doesn't care about the errors.