WISH: as_pkgdown() / pkgdown:::package_vignettes() support any vignette format - not just rmarkdown

[HenrikBengtsson]

Posting partly as a feature request, and partly in case others are trying to figure out why their vignettes are not showing up as "articles" when running pkgdown::build_site().

Issue

pkgdown::build_site() calls pkgdown::build_articles() internally for build "articles" from the package vignettes. However, this will only happen for vignettes under vignettes/ with filename extensions "\\.[rR]md$" and (it looks like) the vignettes should be in Rmarkdown format with a yaml header. For instance, a traditional Sweave vignettes/*.Rnw vignette will be (silently) ignored.

Wish

It would be neat if any R vignette format that R itself supports would be recognized. Not sure if it's useful, but tools::pkgVignettes(dir = pkg) is what R itself uses to parse the package source for vignettes, e.g.

> tools::pkgVignettes(dir = ".")
$docs
[1] "/home/hb/repositories/R.rsp/vignettes/R_packages-Static_PDF_and_HTML_vignettes.pdf.asis"
[2] "/home/hb/repositories/R.rsp/vignettes/R_packages-LaTeX_vignettes.ltx"                   
[3] "/home/hb/repositories/R.rsp/vignettes/Dynamic_document_creation_using_RSP.tex.rsp"      
[4] "/home/hb/repositories/R.rsp/vignettes/R_packages-RSP_vignettes.md.rsp"                  
[5] "/home/hb/repositories/R.rsp/vignettes/R_packages-Vignettes_prior_to_R300.tex.rsp"       
[6] "/home/hb/repositories/R.rsp/vignettes/RSP_intro.html.rsp"                               
[7] "/home/hb/repositories/R.rsp/vignettes/RSP_refcard.tex.rsp"                              

$names
[1] "R_packages-Static_PDF_and_HTML_vignettes"
[2] "R_packages-LaTeX_vignettes"              
[3] "Dynamic_document_creation_using_RSP"     
[4] "R_packages-RSP_vignettes"                
[5] "R_packages-Vignettes_prior_to_R300"      
[6] "RSP_intro"                               
[7] "RSP_refcard"                             

$engines
[1] "R.rsp::asis" "R.rsp::tex"  "R.rsp::rsp"  "R.rsp::rsp"  "R.rsp::rsp" 
[6] "R.rsp::rsp"  "R.rsp::rsp" 

$patterns
[1] "[.](pdf|html)[.]asis$" "[.](tex|ltx)$"         "[.][^.]*[.]rsp$"      
[4] "[.][^.]*[.]rsp$"       "[.][^.]*[.]rsp$"       "[.][^.]*[.]rsp$"      
[7] "[.][^.]*[.]rsp$"      

$encodings
/home/hb/repositories/R.rsp/vignettes/R_packages-Static_PDF_and_HTML_vignettes.pdf.asis 
                                                                                     "" 
                   /home/hb/repositories/R.rsp/vignettes/R_packages-LaTeX_vignettes.ltx 
                                                                                     "" 
      /home/hb/repositories/R.rsp/vignettes/Dynamic_document_creation_using_RSP.tex.rsp 
                                                                                     "" 
                  /home/hb/repositories/R.rsp/vignettes/R_packages-RSP_vignettes.md.rsp 
                                                                                     "" 
       /home/hb/repositories/R.rsp/vignettes/R_packages-Vignettes_prior_to_R300.tex.rsp 
                                                                                     "" 
                               /home/hb/repositories/R.rsp/vignettes/RSP_intro.html.rsp 
                                                                                     "" 
                              /home/hb/repositories/R.rsp/vignettes/RSP_refcard.tex.rsp 
                                                                                     "" 

$dir
[1] "/home/hb/repositories/R.rsp/vignettes"

$pkgdir
[1] "/home/hb/repositories/R.rsp"

$msg
character(0)

attr(,"class")
[1] "pkgVignettes"

UPDATE 2018-08-07: tools::pkgVignettes(dir = ".") example is now using the R.rsp package (was future package)

[hadley]

I'd be happy to review a PR that implemented this, but realistically, I'm unlikely to find the time to do it myself.

[hadley]

I'm closing this issue to recognise that I'm not going to tackle this.

[HenrikBengtsson]

Couldn't it be useful to keep it open for others to find? I doubt I'm the only one who's interested in real vignette support. (Personally I even argue it's important as pkgdown gaining more popularity)

My guess is that it's not that hard to implement support for this. Like you, I don't have spare cycles to attack this one too. But maybe someone else out there has and will resolve this one.

[hadley]

I would, but getting new types of vignette to work is quite challenging, I think it's better to quash your hopes today, rather than leading you on that it might happen in the future.

[HenrikBengtsson]

getting new types of vignette to work is quite challenging

tools::buildVignette() should provide the framework needed to parse vignette metadata and build vignettes. Are you saying there's something beyond this? For instance, that it doesn't fit your plans for the package [even if we would someone would provide a PR for the current version]?

[hadley]

Building the vignette itself is easy enough; it's styling it so that it fits with the rest of the site that's hard (and plumbing together all the nav stuff)

[HenrikBengtsson]

it's styling it so that it fits with the rest of the site that's hard (and plumbing together all the nav stuff)

The formats of vignette products (the "vignette output") are either in HTML or PDF formats. Two follow-up questions:

0. Just linking to HTML/PDF documents seems like a minimal, functional fallback solution.

1. Does pkgdown support Rmarkdown vignettes that produce PDFs? If so, how are you linking to those PDFs right now?

2. Does pkgdown not work with the HTML output of Rmarkdown vignettes? Is it instead "interweaving" the Rmarkdown source, or the Rmarkdown -> Markdown source, into the pkgdown framework/templates which is the built?

PS. Note that I never used pkgdown, hence my possibly rookie questions.

[gsrohde]

As a perhaps not ideal (but perhaps good enough) workaround for this pkgdown limitation, I tried out something like this:

file: vignettes/example.Rmd

---
title: "PDF Vignettes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{PDF Vignettes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r, echo = FALSE}
system('R CMD Sweave vignette_1.Rnw')
system('pdflatex vignette_1.tex')
```

<!--- <iframe src="vignette_1.pdf"/> -->

[Vignette Number 1](vignette_1.pdf){target="_blank"}

This assumes, of course, that there is a file vignettes/vignette_1.Rnw. And there is only one PDF vignette in this "index"; if you have more than one, repeat the vignette compilation code and add a link for each one.

The {target="_blank"} qualifier is to make the PDF file open in a new window or tab since it won't include the navigation structure. (I didn't like the result when I tried using an Iframe.)

The commented-out Iframe is there simply to trick pkgdown into copying the PDF to the right place. There might be a better way, but this was the first I hit upon. (A third system call with cp might work just as well.)

Note that I tried using tools::buildVignette("vignette_1.Rnw") in place of the system calls, but it acted funny and didn't work even though it works fine if run in an R session with vignettes as the current directory. It would simply copy the .Rnw file verbatim to a .tex file, which of course wouldn't compile correctly.

[HenrikBengtsson]

@gsrohde, thanks for this. I think this is a great proof of concept of showing that there's a way forward here.