I'm trying to see the vignette that I've created after rebuilding a package on my local computer. Note that this has nothing to do with suggestions on this post, since I'm not cloning from Github.
The vignettes portion of my vignette file looks like this:
vignette: >
%\VignetteIndexEntry{pack_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
The process is:
Ctr + Shift + K to knit the vignette
Ctr + Shift + B to rebuild the package
Enter browseVignettes("package name")
Get error:
No vignettes found by browseVignettes
I also tried changing knitr::markdown to knitr::knitr, but it didn't help.
Entire vignette top-portion:
---
title: "Random title"
author: "Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{vignette_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
You don't give all the details to say what went wrong, but here is what you need to do:
Vignettes need to be in the package vignettes directory.
If they are anything but Sweave vignettes (and yours is knitr::rmarkdown, according to the header lines you showed us), then you need to tell R about it in the DESCRIPTION file. For your example, you'd need
VignetteBuilder: knitr
in that file, and also have knitr listed in the Suggests, Depends, or Imports lines.
You need to follow the naming convention for your vignette engine. For knitr::rmarkdown, name the file something.Rmd.
You don't need to knit the file yourself. R will do that when it builds the source package. (You can configure RStudio to do this for "Install and Restart"; by default it doesn't.) Even if you haven't knitted the vignette, browseVignettes should find it if you've followed the other steps properly, it just won't display the HTML or PDF output, only the source and extracted R code.
Edited to add: When building and reinstalling the package, it appears that sometimes vignettes aren't included unless the install is done from a .tar.gz file. Use the "Build Source Package" option in the RStudio build pane to get one of those.
Related
My package has a PDF file which I'd like to include as a vignette. There are guides on the internet for doing that with Sweave and R.rsp, but I'd like to use knitr as the vignette engine because we are writing another vignette in Rmd.
My latest attempt has file.pdf and file.pdf.asis inside the vignettes/ folder, with the latter containing these two lines:
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::asis_output}
FWIW, if I use R.rsp as an engine, the second line above can simply contain %\VignetteEngine{R.rsp::asis} and that vignette builds fine, so one suspicion I have is that I am simply using the wrong knitr equivalent.
I've also tried some monstrosities involving a mix of a YAML header and LaTeX inclusion of the PDF, which didn't work either:
---
title: "title"
author: "yes"
output: pdf_document
vignette: >
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
\includepdf{file.pdf}
Thanks to the power of open-source software, I was able to run browseVignettes(), go through my installed packages containing a mix of HTML and PDF vignettes, and eventually check out the source code for the jsonlite package. This led me to a simple solution I thought about but immediately dismissed because I thought it wasn't possible: declare both knitr and R.rsp as vignette engines.
So my package's DESCRIPTION now includes:
VignetteBuilder: R.rsp, knitr
and I have an Rmd vignette containing %\VignetteEngine{knitr::rmarkdown} on its YAML header and a file.pdf.asis containing %\VignetteEngine{R.rsp::asis}.
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
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.
Lately I get a warning for my vignette on Win R Development Version when doing a cran check.
Files in the 'vignettes' directory but no files in 'inst/doc'
This warning only appears with the Win Dev version.
For Mac, AppVeyor and Travis no warning appears.
The problem is, I don't know what the warning wants to tell me.
As far as I know I do not have to put files in inst/doc.
Here is the complete warning message:
Files in the 'vignettes' directory but no files in 'inst/doc':
'Figures.d/Rlogo.png', 'Figures.d/distribution.pdf',
'Figures.d/distributionbar.pdf', 'Figures.d/gapsize.pdf',
'Figures.d/imputations.pdf', 'Figures.d/imputations2.pdf',
'Figures.d/sponsorlogo.jpg', 'Figures.d/statsna.png',
'Figures.d/tsairgap.png', 'Introduction.pdf', 'Introduction.tex',
'RJournal.sty'
In my case, I was getting this issue because I had specified my YAML as per #Claudia's answer, but I had specified rmarkdown as the VignetteBuilder in the DESCRIPTION file. Using VignetteBuilder: knitr in my DESCRIPTION file fixed the problem.
I had a similar issue with an Rmd vignette. I fixed it by changing the YAML header of the vignette to something like this:
---
author: "Name Surname"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{Title of your vignette}
%\usepackage[UTF-8]{inputenc}
---
I fixed the problem with adding the .pdf output of my Vignette to inst/doc
Although I am not sure, if this is the supposed solution, it made the warning disappear.
I was getting the error on more than just the Win R Development version, but for me the fix was adding markdown and knitr in the Suggests field in the DESCRIPTION file. Then, I guess it was clear to the package compiler that the vignette was designated as a markdown/HTML doc.
These lines are in my markdown YAML header:
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Example for estimating the case fatality ratio}
%\VignetteEngine{knitr::knitr}
\usepackage[utf8]{inputenc}
During the compiling of your R package, those files are generated and cause your issue.
You should install the package gitignore, then in the main folder you have to create a text file named ".gitignore" (no extension) and add the address of the files you want to ignore. For example, vignettes/*.pdf
I have been building vignettes with knitr for several months but about 10 days ago, this message appeared after using R CMD build or devtools::build():
It seems you should call rmarkdown::render() instead of knitr::knit2html() because Release.Rmd appears to be an R Markdown v2 document.
I thought it would be linked to text inside the vignette so I reduced it to a minimal reproducible example:
title: "Release"
output:
html_vignette
vignette: >
%\VignetteIndexEntry{Release}
%\VignetteEngine{knitr::knitr}
%\VignetteEncoding{UTF-8}
---
Release
Force evaluation
I tried to force the evaluation of the Rmarkdown adding:
params:
force_v1: TRUE
Change vignette builder
I also tried to replace the VignetteEngine by rmarkdown::render and editing the VignetteBuilder in the Description file. This skips the vignette building as rmarkdowndoes not seem to be a known vignette builder.
Question:
Is there a way to solve this using knitr or alternatively by building vignettes with rmarkdown?
Additional information
I tried to build the package both on Windows and Centos, with different versions. Failing build information can also be found here
I use these settings, and they work:
output: rmarkdown::html_vignette
vignette: >
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{the title}
You should use instead
%\VignetteEngine{rmarkdown::render}
with all the packages up to date.
I am trying to write R Package vignettes using R Markdown. I am using R Studio's package authoring tools.
I have R greater than version 3.0.
I have an .Rmd file in the vignettes folder that contains the following text at the top:
<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{An Introduction to the bootcorrelations package}
-->
I have the following in my DESCRIPTION file:
VignetteBuilder: knitr
Suggests: knitr
When I clean and build or build and reload the package in RStudio, the vignette source is displayed, but not the HTML (i.e., there's no HTML file in inst/man).
How can I get RStudio to automatically create the HTML from an R Markdown Vignette?
I've read through Yihui's post on R Package Vignettes with Markdown and it suggests using a makefile, but this more recent documentation about knitr vignettes suggests that the makefile is no longer required.
I also realise that I could manually create the HTML vignette with a command like this:
library(knitr)
knit(input='vignettes/foo.Rmd', output='inst/doc/foo.md')
library(markdown)
markdownToHTML('inst/doc/foo.md', 'inst/doc/foo.html')
A reproducible example:
Vectorize(dir.create)(c("test", "test/R", "test/man", "test/vignettes"))
cat(
'Package: test
Title: Test pkg
Description: Investigate how to auto-compile markdown vignettes
Version: 0.0-1
Date: 2015-03-15
Author: Jeromy Anglim
Maintainer: Jeromy Anglim <a#b.com>
Suggests: knitr
License: Unlimited
VignetteBuilder: knitr',
file = "test/DESCRIPTION"
)
cat(
'---
title: "Introduction"
author: "Jeromy Anglim"
date: "`r Sys.Date()`"
output: html_document
---
<!--
%\\VignetteEngine{knitr::rmarkdown}
%\\VignetteIndexEntry{Introduction}
-->
# Introduction
A sample vignette!
```{r}
1 + 1
```',
file = "test/vignettes/intro.Rmd"
)
cat(
"#' Nothing
#' This function is only needed so that roxygen generates a NAMESPACE file.
#' #export
nothing <- function() 0",
file = "test/R/nothing.R"
)
library(roxygen2)
library(devtools)
roxygenise("test")
build("test")
Update: Thinking laterally, there are at least three options.
1. Use build_vignettes()
As #Hadley points out, running build_vignettes() from the devtools package will build vignettes and place them in the inst/man directory of the package.
devtools::build_vignettes()
Building the vignette means you get three versions in inst/man:
the Rmd source
the knitted or weaved HTML vignette
and the R code in the code blocks
This is not tied to the build and reload command in RStudio, but it is a one line solution to the task. And it could easily be incorporated into a makefile.
2. Use Knit HTML in Rstudio
As #TylerRinker notes you can just use Knit HTML in Rstudio. This will add both md and HTML knitted versions of the rmd vignette to the vignettes directory.
This also is not tied to the build process but as #TylerRinker points out, often you don't want the vignettes tied to the main build process. This also has the benefit of giving you an md file which can be a nice option for displaying the vignette on github, although http://htmlpreview.github.com/ is an option for displaying HTML vignette on github.
3. Build source package and extract from compressed file
Build - Build Source Package in RStudio corresponds to R CMD build. When run a compressed tar.gz file is created which contains in the inst/doc directory the Rmd, R and HTML files for the original rmd vignette file.
This is described in the official documentation on writing package vignettes which instructs you to use R CMD build to generate PDF and HTML vignettes.
So it is possible to
Build Source
Unzip the tar.gz file
Browse and open the resulting file