knitr - How to get RStudio to automatically compile R Markdown Vignettes?

Question

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 <[email protected]>
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")

Answer 1

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:

1. the Rmd source
2. the knitted or weaved HTML vignette
3. 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

1. Build Source
2. Unzip the tar.gz file
3. Browse and open the resulting file