Search code examples
rpackageknitrvignetternw

How do I 'prebuild' a vignette index for an R package?

I'm preparing a package for submission to CRAN. I use R CMD build myPackage then R CMD check myPackage --as-cran and it passes all checks with no notes or warnings. However, each time I try to submit, I get the following error message from one of the CRAN maintainers:

Package has a VignetteBuilder field but no prebuilt vignette index.

As a start, I'd like to be able to reproduce the above error message on my own system (R version 3.0.1).

The vignette .Rnw file looks like this:

%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{myVignetteName}
\documentclass{article}
\begin{document}
Here is some code:
<<>>=
plot(1:10, 10:100)
@
\end{document}

I have tried adding an INDEX file in the root directory with a vignette entry like this:

myFunction       a brief description
abc-vignette     vignette description

Again, this passes R CMD check myPackage --as-cran but I get the same error message.

I have also tried R CMD build myPackage --md5 to force creation of an MD5 file, to no avail.

When I look at myPackage.Rcheck/00_pkg_src/myPackage/inst/doc I find the vignette files, .Rnw and .pdf as expected.

The package DESCRIPTION file has the following entry:

VignetteBuilder: knitr
Suggests: knitr

When I look at myPackage.Rcheck/myPackage/Meta I see an entry vignette.rds. However this appears to be a binary file, so I can't make sense of it.

This is from 'writing R extensions':

At install time an HTML index for all vignettes in the package is automatically created from the \VignetteIndexEntry statements unless a file ‘index.html’ exists in directory ‘inst/doc’. This index is linked from the HTML help index for the package. If you do supply a ‘inst/doc/index.html’ file it should contain relative links only to files under the installed ‘doc’ directory, or perhaps (not really an index) to HTML help files or to the ‘DESCRIPTION’ file.

So do I need to manually create index.html and could anyone point to an example of what this should look like?

This question appears closely related, but I do not (knowingly) have an .Rbuildignore file. This is also related, although I'm not using devtools for package creation. I have also looked at this question but am not seeing an easy answer.

Update Jul 1

For a reproducible example, the package is available here on github. Downloading and installing (e.g. with devtools::install_github() should allow this error to be reproduced.

Solution

  • I gather the Vignette commands need to be in the preamble, i.e. below documentclass, so that the file myVignette.Rnw should read:

    \documentclass{article}

% \VignetteIndexEntry{myVignette}
% \VignetteEngine{knitr::knitr}

\usepackage[]{graphicx}
...

    This seems to work fine.

    The error message is from the development version of R CMD check which is currently 3.3.0. I have been using the older 'stable' version which is not the recommended way to check packages when considering submission to CRAN.

    I'm still not sure of the merits of using a manual index.html file - it appears unnecessary but I will gladly change the accepted answer if anyone can throw some light on this.