[jira] [Created] (ARROW-17655) Pre-render vignettes

["Sam Albers (Jira)" <ji...@apache.org>]

Sam Albers created ARROW-17655:
----------------------------------

             Summary: Pre-render vignettes
                 Key: ARROW-17655
                 URL: https://issues.apache.org/jira/browse/ARROW-17655
             Project: Apache Arrow
          Issue Type: Improvement
          Components: R
            Reporter: Sam Albers


Working on ARROW-17448 made me think about how one can pre-render vignettes to a) test that the code in them works but b) does not impose the burden of rendering them on CRAN which is not possible. 

The basic idea would be to convert the existing rmd vignettes into files that knitr::knit can work with and then output pre-rendered rmds that can be shipped directly to CRAN. Here is a reprex that illustrates this approach:

Make a .Rmd.raw file:

 
{code:java}
tdir <- tempdir()
## write a vignette but write it as *.Rmd.raw
writeLines(
    r"(---
title: "a great vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{a great vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r options, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, 
                      warning = FALSE, 
                      message = FALSE, 
                      fig.path = "vignette-fig-")
```
## Some text and code
here is `quakes`
```{r}
head(quakes)
```
and here is a plot of quakes:
```{r, echo = FALSE}
plot(quakes)
```)",  
    con = file.path(tdir, "great-vignette.Rmd.raw")
)
{code}
Then render it and output an .Rmd:



 
{code:java}
## find the vignette
raw_vignette <- file.path(list.files(path = tdir, pattern = "*\\.Rmd\\.raw", full.names = TRUE))
rendered_vignette <- tools::file_path_sans_ext(raw_vignette)
## knit the file and outputs an Rmd ready for CRAN that has all the results
knitr::knit(raw_vignette, rendered_vignette, quiet = TRUE)
{code}

which results in a pre-rendered Rmd:
{code:java}
cat(readLines(rendered_vignette), sep = "\n")

---
title: "a great vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{a great vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Some text and code
here is `quakes`
```r
head(quakes)
```
```
##      lat   long depth mag stations
## 1 -20.42 181.62   562 4.8       41
## 2 -20.62 181.03   650 4.2       15
## 3 -26.00 184.10    42 5.4       43
## 4 -17.97 181.66   626 4.1       19
## 5 -20.42 181.96   649 4.0       11
## 6 -19.68 184.31   195 4.0       12
```
and here is a plot of quakes:
![plot of chunk unnamed-chunk-2](vignette-fig-unnamed-chunk-2-1.png)
{code}
No worries if we don't want to take this approach. It would require running the vignettes on someone's machine prior to a CRAN submission. That could go in the Makefile: https://github.com/apache/arrow/blob/master/r/Makefile

 

 

 



--
This message was sent by Atlassian Jira
(v8.20.10#820010)