Skip to content

Consider changing \dontrun in examples to \donttest #208

@capnrefsmmat

Description

@capnrefsmmat

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 by example() but not by R 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() or nzchar(Sys.which("someprogram")) to test for features needed in the examples wherever possible, and you can also use try() or tryCatch(). Use interactive() 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 the DESCRIPTION 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions