I recently released a vignette with version 1.1 of my R package. The Rmd for the vignette can be found here. When I create the vignette locally, I see author information and the table of contents at the top of the vignette, as expected. However, when I submitted this package to CRAN and the vignette was created there, I no longer see the table of contents or author information. Does anyone know why this may be happening?
Thanks.
I glanced at your DESCRIPTION here and noticed that the VignetteBuilder field does not contain rmarkdown. Since you are using knitr::rmarkdown as an engine, I suspect that you need:
VignetteBuilder: knitr, rmarkdown
Here is a relevant paragraph from the R-exts manual:
The VignetteBuilder field names (in a comma-separated list) packages that provide an engine for building vignettes. These may include the current package, or ones listed in Depends, Suggests or Imports. The utils package is always implicitly appended. See Non-Sweave vignettes for details. Note that if, for example, a vignette has engine knitr::rmarkdown, then knitr provides the engine but both knitr and rmarkdown are needed for using it, so both these packages need to be in the VignetteBuilder field and at least suggested (as rmarkdown is only suggested by knitr, and hence not available automatically along with it). Many packages using knitr also need the package formatR which it suggests and so the user package needs to do so too and include this in VignetteBuilder.
This is not a guaranteed fix, but it is maybe a first step.
Related
Is there any way I can include links between package vignettes in R? I know I can link between section, for example
# Section 1 {#section1}
My first section
# Section 2
A link to [Section 1](#section1)
But is there any way I can get a clickable link that will launch the HTML doucment of another vignette? Or is it just easier to give the code to launch it?
```r
vignette("my vignette", package = "myPackage")
```
Note I have generated all of my vignettes using Rmarkdown and knitr.
Yes, this is simple. Vignettes are all stored in the same directory, so you simply refer to the appropriate file name. The drat package vignettes have several examples of this. Here is a link from one vignette to the other:
This vignette deals with the first case: How to use
[drat](http://dirk.eddelbuettel.com/code/drat.html) as a package author. A
[companion vignette for package users](DratForPackageUsers.html) is available as well.
This will work on CRAN and on a user's machine.
You should also be able to link from vignettes to documentation, and vice versa, on a user's machine, knowing that vignettes are stored in library/PKGNAME/doc/ and documentation is stored in: library/PKGNAME/html/.
I've been reading through R's Affy manual, and it refers to other vignettes. Does the difference between these two terms simply relate to quantity of content, or is there more to it?
Reference Manuals
The reference manual of a package is a single document beginning with the package description and containing all of the content from the .Rd help files for the packages. Generally, this means it has the help files for (exported) functions in the package, any documented data sets, and package-level documentation (if included). It is automatically generated from the .Rd sources.
Every package has a manual. Even a package with no exported functions and documentation would still have a manual (when built) consisting of the text from the Description file.
Vignettes
Vignettes are free-form documents. Generally, package authors use them to demonstrate the use of their package. They are optional, some packages have several (as I write this dplyr has 8 vignettes) and many packages have none.
As mentioned in the comments the R Extensions Manual is the definitive source for all things package-related. Here is Josh's link to the Vignettes Section, and 2.15 Processing documentation files describes how reference manuals are built.
The knitr package has relatively recently added new notangle vignette engines, such as knitr::rmarkdown_notangle, that allow disabling of evaluation of vignette chunks. The general process of using knitr for vignettes is described here, while the specific notangle functionality is described in an answer to this question.
My problem is that I can't get this to work. I can get it to pass R CMD build by including the .html output in the vignettes directory (I also put a copy in inst/doc), but I can't get it to pass R CMD check unless I specify --no-build-vignettes, or unless I change the rmarkdown_notangle engine back to rmarkdown.
I have built a trivial package that contains the following vignette (in vignettes/notangle.rmd): it's available here.
<!--
%\VignetteEngine{knitr::rmarkdown_notangle}
%\VignetteIndexEntry{Supplementary Materials}
-->
A silly little vignette.
```{r}
2+2
```
My DESCRIPTION file includes
Suggests:
knitr,
VignetteBuilder: knitr
BuildVignettes: yes
When I try to run R CMD check I get
* checking re-building of vignette outputs ... NOTE
Error in re-building vignettes:
...
Error: processing vignette 'notangle.rmd' failed with diagnostics:
Failed to locate the ‘weave’ output file (by engine ‘knitr::rmarkdown_notangle’)
for vignette with name ‘notangle’. The following files exist in directory ‘.’:
‘notangle.rmd’
Using r-devel (2014-09-17 r66626), but also happens with 3.1.1.
The workaround (which I would strongly prefer to avoid) is to switch from R code chunks to generic code chunks (opens with triple-backtick, rather than triple-backtick+"r"), which Rmarkdown doesn't process.
I'm sure I'm doing something boneheaded. Any clues?
update: I can get what I need (stop all chunks from being evaluated) by explicitly adding eval=FALSE to the options of every chunk, but I'd still like to know what's going on ...
It is a bug in the current version of knitr, and it has been fixed in the development version 1.7.9, which will (hopefully) be v1.8 on CRAN in the future.
I'm writing a vignette for one of my packages.
In this vignette, I would like to demonstrate how this package can interact with other packages that are not being imported by the NAMESPACE or by the Imports section of the DESCRIPTION file.
So, I'm putting a require call to use these external packages in my vignette, but of course I got the following NOTE when I try to R CMD check the package:
* checking for unstated dependencies in vignettes ... NOTE
‘library’ or ‘require’ call not declared from: ‘RColorBrewer’
Is there any way around this, or should I either import these external packages or "fake" the vignette using eval=FALSE?
Put it in Suggests: of your DESCRIPTION file.
From p. 6 of the R extensions manual:
The ‘Suggests’ field uses the same syntax as ‘Depends’ and lists
packages that are not necessarily needed. This includes packages used
only in examples, tests or vignettes (see Section 1.4 [Writing package
vignettes], page 26), and packages loaded in the body of functions.
E.g., suppose an example from package foo uses a dataset from package
bar. Then it is not necessary to have bar use foo unless one wants to
execute all the examples/tests/vignettes: it is useful to have bar,
but not necessary. Version requirements can be specified, and will be
used by R CMD check.
In addition if the vignette properly depends on that package, there should be a
% \VignetteDepends{...}
statement in the vignette itself: Sweave, Part II: Package Vignettes, R News 3/2 (Oct. 2003), 21 - 24.
However, your case possibly is a bit different:
I use if (require ("pkgxy")) without % \\VignetteDepends{pkgxy} (Suggests: pkgxy in the DESCRIPTION is needed anyways) for some things I want to show but where I don't want to force the user to have all the suggested pacakges installed. I put a box at the beginning of the vignette where I report which of those packages are available and if a package is not available when the vignette is built, an "pkgxy is needed to do this" text is put into the vignette.
The "introduction" vignette of package hyperSpec is an example (to find out how it actually works, you need not only the .Rnw but also some more definitions).
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.