I am new to writing R packages. I'm trying to learn how to make a vignette for my package. I have created a vignettes folder with a file "getting-started.Rmd"
---
title: "WaterML Tutorial"
author: "Jiri Kadlec"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to the WaterML R package}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Quick Start
This simple example shows how to get started with the <my R package>.
To build the vignette I use the command:
devtools::build_vignettes()
Then I run Rcmd.exe INSTALL my_package, and to view my vignette I run:
browseVignettes("my_package")
However I only see the vignettes in the html and source format:
As you see in the screenshot, there's no "pdf" option. How do I configure my .Rmd file to create my vignette in the pdf format?
In your header, you are telling R to output only an html vignette in line:
output: rmarkdown::html_vignette
If you want pdf, try:
output: pdf_document
According to R packages:
Output: this tells rmarkdown which output formatter to use. There are many options that are useful for regular reports (including html, pdf, slideshows, …) but rmarkdown::html_vignette has been specifically designed to work well inside packages. See ?rmarkdown::html_vignette for more details.
So you might have a few small problems using a raw pdf.
At this time, rmarkdown does not have a output: rmarkdown::pdf_vignette option
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}.
My apologies in advance if this is an obvious question but I have searched both stack overflow and what have been otherwise very useful resources like R packages by Hadley Wickham or this blog and can not find an answer.
My issue occurs when trying to run build_vignettes() on my developed R package (myPackage). The vignette for the package (myPackage.Rmd) will create as expected using knit in RStudio but when I run build_vignettes(), I get the following error:
> devtools::build_vignettes()
Building cosni vignettes
--- re-building ‘myPackage.Rmd’ using rmarkdown
--- finished re-building ‘myPackage.Rmd’
Error: Directory '✓ Setting active project to \'path/to/package/directory/'' does not exist.
The top of my myPackage.Rmd file is:
---
title: "A title"
date: "`r Sys.Date()`"
author: "Name"
output:
html_document:
toc: true
toc_float: true
number_sections: true
theme: "paper"
pdf_document:
toc: true
vignette: >
%\VignetteIndexEntry{A title}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---
This file is located in the vignettes folder of my package folder. There are also 3 png images in this folder which are called in the myPackage.Rmd file as follows:
```{r, echo=FALSE, out.width = '98%', out.height='98%'}
knitr::include_graphics("an_image.png")
```#
Otherwise the vignette only contains text.
The package will run and I can install it locally with either devtools::build() or
devtools::install(build_vignettes = TRUE) they will work but then when I run browseVignettes("myPackage") and click on the HTML, source or R code I get the following error:
Not Found
The requested URL /library/myPackage/doc/myPackage.html was not found on this server.
Also, in the package's DESCRIPTION file I have included the following:
Suggests:
knitr,
rmarkdown
VignetteBuilder: knitr
----------- EDIT --------------
Through repeatedly trying to get the devtools::build_vignettes to work I have noted that sometimes I get the following error rather than the first I mentioned:
> devtools::build_vignettes()
Building cosni vignettes
--- re-building ‘myPackage.Rmd’ using rmarkdown
--- finished re-building ‘myPackage.Rmd’
Error in if (dir_exists(path %||% "") && is_in_proj(path)) { :
missing value where TRUE/FALSE needed
I solved the second error you get updating packages devtools and usethis.
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.
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 have a vignette for my package which compiles to a nice PDF when compiled with Rscript -e 'rmarkdown::render("tmod.rmd")'. However, when I compile and install the package, start R and type vignette("mypackagename"), a browser window opens with ugly looking HTML, without a title, without a table of contents and without references.
However, if I compile the vignette manually to pdf before creating the package, it shows up just fine.
What went wrong? Why is my PDF not generated automatically when I compile the package?
In the markdown file header, I have
---
title: "foo foo foo"
author: "Foofooary Finer"
date: "`r Sys.Date()`"
output:
pdf_document:
vignette: >
%\VignetteIndexEntry{FooFoo}
%\VignetteKeyword{foo}
%\VignetteEngine{knitr::knitr}
%\SweaveUTF8
\usepackage[utf8](inputenc)
abstract: |
foo foo foo foo foo
toc: yes
bibliography: bibliography.bib
---
In the package DESCRIPTION file, I have
VignetteBuilder: knitr
Suggests: knitr
When I asked the same question on the knitr google group, Yihui Xie (author of knitr) replied:
Use the vignette engine knitr::rmarkdown instead of knitr::knitr.
I'm not entirely sure I understand why, but it works. Here is a link to discussion on the knitr google group.