Package build fails because vignette does not find child Rmd files

Question

I have modularized my vignette Rmd file using child chunks to be able to reuse the child Rmd files in other Rmd documents.

The package build fails (in RStudio and with R CMD build .) with this error message:

** installing vignettes
   ‘Vignette.Rmd’ using ‘UTF-8’ 
Warning in readLines(if (is.character(input2)) { :
  cannot open file 'child_doc.Rmd': No such file or directory
Quitting from lines 10-11 (child_doc.Rmd) 
Error in readLines(if (is.character(input2)) { : 
  cannot open the connection
ERROR: installing vignettes failed

How can I build my package (make R find my child Rmd files)?

Example Rmd files:

Vignette.Rmd

---
title: "title"
author: "me"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{title}
  %\VignetteEngine{rmarkdown::render}
  %\VignetteEncoding{UTF-8}

main doc

```{r child = "child_doc.Rmd"}
```

child_doc.Rmd:

# This is from the child doc
lorem ipsum

Update 1:

https://stackoverflow.com/a/49463061/4468078 indicates that RStudio builds the vignettes with the package folder as root (which could explain why the files are not found).

Update 2:

If have created a minimal reproducible example package together with a summary of the findings at github:

https://github.com/aryoda/R_pkg_knitr_child_vignette_issue

Update 3:

I have opened an issue at knitr (https://github.com/yihui/knitr/issues/1540) but @user2554330 has identified the tools namespace as one reason of problems...

Update 4:

See the bugzilla bug entry opened by Duncan Murdoch: https://bugs.r-project.org/bugzilla3/show_bug.cgi?id=17416

Answer 1

This looks like a bug (or maybe more than one). I'd probably call it a bug in R, but it might be a bug in knitr. When you build the tarball, R copies the main file into inst/doc, but not the child file. knitr then looks at it and since it doesn't see the child, it quits.

To get the package to build, you just need an empty file in inst/doc with the same name as the child file. But this isn't enough to pass checks.

When checking the package, R will see that child file sitting in inst/doc, and get upset because it's not a proper vignette. So you need to fool R into thinking it is one.

As far as I can see, there's an easy (though ugly) workaround. Just put a file named child_doc.Rmd into the inst/doc directory. To make R think it is a vignette, copy the lines

  %\VignetteIndexEntry{title}
  %\VignetteEngine{rmarkdown::render}
  %\VignetteEncoding{UTF-8}

from the main file. Otherwise, the content appears to be irrelevant, so I wouldn't put anything else there.

Put the real child_doc.Rmd file into the vignettes directory. I think if you do this, your package will build and check without errors.

This is probably worth a bug report, but I'm not sure what the fix should be. Maybe knitr should be more tolerant in its check, or maybe R should copy the file sooner.

Too bad the workaround is so ugly, and will probably cause other problems once the bug is fixed.