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

[Kevin R Coombes]

Produce a PDF file yourself, then use the "as.is" feature of the R.rsp 
package.

Specifically, include this line in your DESCRIPTION file:
VignetteBuilder: R.rsp

Let's say the pdf file is called "myfile.pdf".  Create a file called 
"myfile.pdf.asis" that contains the vignette instructions. Put it in the 
vignette directory along with the PDF file. Mine looks like:

%\VignetteIndexEntry{PUT VIGNETTE TITLE HERE}
%\VignetteKeywords{PUT KEYWORDS HERE}
%\VignetteDepends{PACKAGE_NAME}
%\VignettePackage{PACKAGE_NAME}
%\VignetteEngine{R.rsp::asis}

I am not certain if this works for an HTML vignette, but I see no reason 
why it shouldn't.

Best,
   Kevin

On 10/16/2023 10:14 AM, John Fox wrote:
> 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://github.com/gmonette/cv>.
>
> 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