[R-pkg-devel] Suppressing long-running vignette code in CRAN submission

Tue Oct 17 20:56:08 CEST 2023

Hello Georgi,

On 2023-10-17 2:36 p.m., Georgi Boshnakov wrote:
> Caution: External email.
> 
> 
> Hello John,
> 
> It should work for the scenario where you as developer and CRAN's checks should both be happy. 

Thank you for addressing that question. I was concerned that CRAN would 
rebuild the vignette for the tarball that they distribute, which then 
would have no output.

In the interim, I implemented the approach using the R.rsp package 
suggested by Kevin and Dirk. It seems to work OK. A downside is that we 
have to maintain two versions of the package -- one for development, 
using knitr to build the HTML vignettes and the other using R.rsp with 
the HTML vignettes pre-built.

> But there are other scenarios were it might not work.
> 
> For example, if a user wishes to build a local pkgdown site for your package, they would need to know to set that environment variable. I also see that you have pkgdown actions on the github repo but the eval option is commented out there
> 
>       # eval = nzchar(Sys.getenv("REBUILD_VIGNETTES"))
> 
> Even so, I don't see the vignette on the rendered site. The same thing I observed when I cloned the package, uncommented the 'eval' option, and run pkgdown. Of course you  could modify the pkgdown action to set the environment variable.
> I don't know why pkgdown doesn't include the vignette 'cv' (it includes the other one).

Yes, both vignettes are there. One is under "Get Started" (I believe 
because the vignette is in cv.html, with the same name as the package) 
and the other under "Articles."

> 
> Also when the vignette is created without evaluating the code it would be useful to include a very visible message, explaining how to create the full one.

Thanks for the suggestion. We'll think about this, though the process of 
creating the vignettes is already getting more complicated than I'd like.

> 
> All in all, some of the solutions recommended by others seem preferable.

Using R.rsp has the disadvantage of not including useful vignette 
sources in the tarball and thus installed package, but since it seems to 
be a well-used approach, I think we'll probably go with it.

Thanks again,
  John

> 
> Georgi Boshnakov
> 
> 
> -----Original Message-----
> From: R-package-devel <r-package-devel-bounces using r-project.org> On Behalf Of John Fox
> Sent: Tuesday, October 17, 2023 3:03 PM
> To: Dirk Eddelbuettel <edd using debian.org>
> Cc: r-package-devel using r-project.org
> Subject: Re: [R-pkg-devel] Suppressing long-running vignette code in CRAN submission
> 
> Hello Dirk,
> 
> Thank you (and Kevin and John) for addressing my questions.
> 
> No one directly answered my first question, however, which was whether the approach that I suggested would work. I guess that the implication is that it won't, but it would be nice to confirm that before I try something else, specifically using R.rsp.
> 
> Best,
>    John
> 
> On 2023-10-17 4:02 a.m., Dirk Eddelbuettel wrote:
>> Caution: External email.
>>
>>
>> On 16 October 2023 at 10:42, Kevin R Coombes wrote:
>> | Produce a PDF file yourself, then use the "as.is" feature of the
>> | R.rsp package.
>>
>> For completeness, that approach also works directly with Sweave.
>> Described in a blog post by Mark van der Loo in 2019, and used in a
>> number of packages including a few of mine.
>>
>> That said, I also used the approach described by John Harrold and
>> cached results myself.
>>
>> Dirk
>>
>> --
>> dirk.eddelbuettel.com | @eddelbuettel | edd using debian.org
>>
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/r-pa
>> ckage-devel__;!!PDiH4ENfjr2_Jw!F7whfpm7565Ira_DwkEbOj5wjzyL-WztVmqP5Ak
>> 56oOGw4wkUyMiLVCOno76H-Iu2wVBvuVMWoYaUtEdjWOx0vfSzv8t$
>> [stat[.]ethz[.]ch]
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/r-package-devel__;!!PDiH4ENfjr2_Jw!F7whfpm7565Ira_DwkEbOj5wjzyL-WztVmqP5Ak56oOGw4wkUyMiLVCOno76H-Iu2wVBvuVMWoYaUtEdjWOx0vfSzv8t$ [stat[.]ethz[.]ch]
> 
> Dear list members,
> 
> I believe that this issue has been discussed previously, but I'm not sure that I have the solution right.
> 
> Georges Monette and I have developed a package that we intend to submit soon to CRAN which has a vignette including code that takes a long time to run. The sources for the package are available at <https://urldefense.com/v3/__https://github.com/gmonette/cv__;!!PDiH4ENfjr2_Jw!BUIYcAjj16HHKVqI_3EssWXnTOQ1Sz95Vv_aF1ebj4qCCayUfxFKDASOpfkJhK4YTWTDJsbDgRVAHngMjRyqzrZC5Wsa$ [github[.]com]>.
> 
> We figure that we have to suppress running the code the vignette when CRAN checks the package or the check time will be excessive.
> 
> The vignette is written as a .Rmd file to be compiled by knitr, producing an HTML vignette. The top of the .Rmd file looks like this:
> 
> ------- snip -------
> 
> ---
> title: "Cross-validation of regression models"
> author: "John Fox and Georges Monette"
> date: "`r Sys.Date()`"
> package: cv
> output:
>     rmarkdown::html_vignette:
>     fig_caption: yes
> bibliography: ["cv.bib"]
> csl: apa.csl
> vignette: >
>     %\VignetteIndexEntry{Cross-validation of regression models}
>     %\VignetteEngine{knitr::rmarkdown}
>     %\VignetteEncoding{UTF-8}
> ---
> 
> ```{r setup, include = FALSE}
> knitr::opts_chunk$set(
>     collapse = TRUE,
>     message = TRUE,
>     warning = TRUE,
>     fig.align = "center",
>     fig.height = 6,
>     fig.width = 7,
>     fig.path = "fig/",
>     dev = "png",
>     comment = "#>",
>     eval = nzchar(Sys.getenv("REBUILD_CV_VIGNETTES"))
> )
> 
> ### other irrelevant setup code not shown ###
> 
> ```
> 
> ------- snip -------
> 
> So (near the bottom), if the environment variable REBUILD_CV_VIGNETTES isn't empty, the code blocks in the vignette are evaluated, otherwise not. To build the tarball for the package to be submitted to CRAN, we will set REBUILD_CV_VIGNETTES to "true". That works as intended.
> 
> If we submit the tarball to CRAN, I believe that the package as distributed by CRAN will include the HTML vignette from our tarball, showing the evaluated code blocks, but when CRAN checks the package, these long-running code blocks will not be executed (because REBUILD_CV_VIGNETTES will not exist on the CRAN check machines).
> 
> My questions:
> 
> Is that correct?
> 
> If not, how can we ensure that the complete vignette is distributed by CRAN without causing an overly long CRAN check time?
> 
> In particular, we don't want CRAN to rebuild and distribute the vignette, because the resulting HTML file won't show the evaluated code.
> 
> Any assistance would be appreciated.
> 
> Thank you,
>    John
> --
> John Fox, Professor Emeritus
> McMaster University
> Hamilton, Ontario, Canada
> web: https://urldefense.com/v3/__https://www.john-fox.ca/__;!!PDiH4ENfjr2_Jw!BUIYcAjj16HHKVqI_3EssWXnTOQ1Sz95Vv_aF1ebj4qCCayUfxFKDASOpfkJhK4YTWTDJsbDgRVAHngMjRyqzheH0nJ3$ [john-fox[.]ca]
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/r-package-devel__;!!PDiH4ENfjr2_Jw!BUIYcAjj16HHKVqI_3EssWXnTOQ1Sz95Vv_aF1ebj4qCCayUfxFKDASOpfkJhK4YTWTDJsbDgRVAHngMjRyqzih743zY$ [stat[.]ethz[.]ch]