R Package Vignettes with Markdown

[This article was first published on Yihui Xie, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

What is the best resource to learn an R package? Many R users know the almighty question mark ? in R. For example, type ?lm and you will see the documentation of the function lm. If you know nothing about a package, you can take a look at the HTML help by

help.start<span class="p">()</span>

where you can find the complete list of documentation by clicking the link Packages. The individual help pages are often boring and difficult to read, because you cannot see the whole picture of the elephant. That is where package vignettes can help a lot. A package vignette is like a short paper (in fact some are real journal papers), which gives you an overview of this package, and sometimes with examples. Package vignettes are not a required component of an R package, so you may not find them in all packages. For those packages which contain vignettes, you can find them by browseVignettes(), e.g. for the knitr package

browseVignettes<span class="p">(</span>package <span class="o">=</span> <span class="s">'knitr'</span><span class="p">)</span>
<span class="c1"># or go to</span>
system.file<span class="p">(</span><span class="s">'doc'</span><span class="p">,</span> package <span class="o">=</span> <span class="s">'knitr'</span><span class="p">)</span>

You can also see links to vignettes from help.start(): click Packages and go to the package documentation, or

help.start<span class="p">()</span>
browseURL<span class="p">(</span>paste0<span class="p">(</span><span class="s">'http://127.0.0.1:'</span><span class="p">,</span> tools<span class="p">:::</span>httpdPort<span class="p">,</span>
          <span class="s">'/library/knitr/doc/index.html'</span><span class="p">))</span>

Most vignettes are written in LaTeX/Sweave since that is the official approach (see Writing R Extensions). In the past Google Summer of Code, Taiyun Wei explored a few interesting directions of the knitr package, and one of them was to build HTML vignettes for R packages from Markdown, which is much easier to write than LaTeX.

For package authors who are interested, Taiyun’s corrplot package (on Github) can serve as an example. The markdown vignette is inst/doc/index.Rmd, and it is built to HTML by knitr with the Makefile. When you run R CMD build corrplot, index.Rmd will be converted to index.html, which you can view it in help.start() after R CMD INSTALL corrplot_*.tar.gz (DO NOT use devtools::install_github() here because it does not run R CMD build).

The Makefile should be pretty clear: it is merely a call to knitr::knit2html(). The vignette index.Rmd is a simple R Markdown document; if you are not familiar with this format, see this video for a brief introduction:

Note you need

  1. Suggests: knitr in your package DESCRIPTION file to pass R CMD check, and
  2. a fake *.Rnw file under inst/doc/ to trigger the Makefile

Once you have this HTML vignette, you can also publish it elsewhere. For example, either RPubs.com or GitHub pages to gain more publicity (see an example of the phyloseq package). It is important to let users be aware of package vignettes, and a web link is apparently easier to tell other people than browseVignettes() (I felt very uncomfortable when I was writing the first half of this post because the vignettes are hidden so deep, hence so hard to describe).

So why not start building an HTML vignette for your package with R Markdown now? Think about animations, interactive content (e.g. googleVis), MathJax equations and other exciting web stuff.

To leave a comment for the author, please follow the link and comment on their blog: Yihui Xie.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)