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.
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.
This may help, or you can turn to devtools to build your package.
Related
I am building an R package. I have several vignettes that I would like to include links to in my README.Rmd.
I know that vignettes are to be built optionally when installing the package.
I do not really understand where I should start. I am in the process of building the package in R studio. I would the user to be able to see the vignette just by clicking at link in the readme on GitHub. Is this possible? How?
The following obviously does not work.
[The main vignette](vignettes/Vignette.html)
You can do this, but it might be more trouble than it's worth.
The problems are
Your package directories are different in the source on Github than they are when your package is installed in R. The link you give would be fine if you actually put Vignette.html in the vignettes directory, but when your package is installed, it will be in doc.
RStudio won't put the processed vignette in either of those locations by default if you just knit Vignette.Rmd.
You don't normally commit output files on Github.
So here's what you could do to work around this. Make the link look like
[The main vignette](doc/Vignette.html)
To make sure that file is there on Github, in RStudio create the doc directory and run
rmarkdown::render("vignettes/Vignette.Rmd", output_file="doc/Vignette.html")
You'll need to commit the output file and push it to Github, but you don't want to include it when you build the .tar.gz file, so you'll also need to add the lines
^doc$
^doc/Vignette.html$
to the .Rbuildignore file in the main package directory.
With all these changes I think your vignette will be visible on Github and also after you install the package in R.
A much simpler approach is just to tell the user to run
vignette("Vignette", package = "yourpackagename")
after installing the package, but this won't make it visible on Github.
If I use devtools::use_vignette("my-vignette") in my package, running devtools::build_vignette() works fine.
However, once I add a call to anything from my package, it stops working, with error could not find function "myfunc". If I add a library(mypackage) call, I get the error there is no package called 'mypackage'.
(I should note that my package checks, builds & installs perfectly cleanly [with no vignettes], and running devtools::load_all() also works fine for interactive sessions.)
I know that if I build & install my package, I can then get the vignettes built. This seems like a really inefficient and dangerous way to develop; essentially forcing me to re-build and re-install the entire package on every commit, to test that the vignette isn't breaking.
Is there another way to get the vignette to recognize the package-in-progress?
If you are using RStudio IDE (which is very helpful for package developpement), you can render your Rmd document created by devtools::use_vignette, by clicking on the Knit button. It will create a preview version of your vignette.
By the way, RStudio IDE provides you with helpful shortkeys and buttons to execute your Rmd document chunk by chunk to test if it's working.
If you are not using RStudio IDE, you could render your document without building the package by using the function rmarkdown::render.
However, in order to be working, your vignette requires your package to be loaded. So, as you said, you'll have to call library(mypackage) and so your package have to be installed.
You can install your package without the vignette in the command line with devtools::install(build_vignette = FALSE). In the RStudio IDE, the button Build & Reload is enougth to intall your package.`
Another solution for non user of Rstudio IDE is to use devtools::load_all(path to your package) in your vignette in order to simulate the installation of your package in the vignette environment. Then you can build your vignette with devtools::build vignette whithout needing to install your package before.
I should underline that vignette is build automatically when your build your package. So, when development are finish, replace in the vignette devtools::load_all by library because your package is loaded before building the vignette when you build a package.
If you look up Hadley Wickham's packages in github, you will see he includes a library(xyz) at the top of his vignette, e.g. https://github.com/tidyverse/dplyr/blob/master/vignettes/dplyr.Rmd
Then his recommended way to build vignettes works:
You can build all vignettes from the console with
*devtools::build_vignettes()*, but this is rarely useful. Instead
use devtools::build() to create a package bundle with the vignettes
included.
I believe this is what you will need to submit a package to CRAN.
It is a slow development cycle, though, so for active coding, you can insert a line with devtools::load_all() to use the knit in RStudio.
I know there is already an answer but this is how I solved the same issue when using a hand written vignette.
I'm not sure if this will work for build_vignette() but when I was having trouble knitting my vignette because of this same error, what I had to do was:
<path/to/your/Rpackage>/NAMESPACE I had to add export(myFuncName) for each function I want to use in the vignette along with useDynLib(myPackageName) once.
I had to specify a VignetteBuilder option in the <path/to/your/Rpackage>/DESCRIPTION file for me it is VignetteBuilder: knitr.
I just recently submitted an update of my package to CRAN, and I was notified that a line in an .Rd file was too wide. Using the latest Rpatched version, I ran the R CMD check, everything checked out ok. I ran the --as-cran on the tarball and everything is ok. When I examined the .PDF file created after R CMD build, I do see that the line in the .PDF help file extended beyond page margin.
My question is where and how do I check for errors in the creation of the .PDF file? I've checked through Writing R Extensions, etc. and I can't find a specific statement.
Build and check your package R CMD build mypkg && R CMD check mypkg_1.2.3.tar.gz. Then look in mypkg.Rcheck/Rdlatex.log for warnings (like Overful \hbox) while processing the Rd file to latex.
I am building a package in R 3.1.0 on Windows 7 32-bit (and also on a different machine running Windows 8 64bit) and I am using knitr to write vignettes using Markdown. I am hoping to publish this package on CRAN so I am using R CMD check to check that my demos, datasets and vignettes all behave properly. I keep my vignettes as .Rmd files (rather than making them outside of the package building process and stashing them in inst/doc) because they serve as extra tests on my package and aren't very big anyway.
My problem is that R CMD check fails when building my vignettes, even though if I run R CMD build and then R CMD INSTALL --build everything works out fine. Looking at the log file, it appears to be failing because it tries to evaluate code that I have explicitly told knitr NOT to evaluate. As a generic example, if I write
```{r example-chunk eval=c(1:3, 5:6), tidy=FALSE}
foo = 5
bar = 3
## don't evaluate the next line
file.show("i/dont/really/exist.csv")
## ok, start evaluating again
foobar = foo*bar
```
In a .Rmd file, running R CMD check will fail because it will try to evaluate line 4. However, the chunk will be correctly evaluated if I run R CMD build mypackage and then R CMD install --build mypackage.tar.gz (I know this because I can go to my Rlibs folder and find the flawless html vignettes in mypackage/doc. Similarly, the chunk will also be evaluated correctly I if run R CMD Sweave to build the vignette.
If you want to try this yourself, the package I am building (where I am running into the issue) is on Github: https://github.com/mkoohafkan/flowdurr-edu. You can look at raw/packagemaker.html for instructions, hopefully it's straightforward (the R code runs through the process of making the package directory, building the help files and copying some manually edited files into the package directory). R CMD check fails on all of my vignettes: when building flowdurr-datasets.Rmd, it insists on evaluating a line with a fake path even though I told it not to. When building hspf-analysis.Rmd, R CMD check insists on evaluating a line I excluded because it takes a really long time to complete (using rgenoud to fit some distribution parameters). R CMD check also fails on vignette.Rmd, but for a different reason; I purposely throw errors to show examples of what you can't do with a particular function, and while knitr doesn't have a problem with it R CMD check sure does!
EDIT: My build script was getting some hate so I made this dummy package that reproduced the problem on both of my machines. It illustrates that 1) R CMD check evaluates a line that it shouldn't, and 2) R CMD check does not support error evaluation in a vignette, even though knitr will write error output without issue.
So I guess my question is: What is it that R CMD check is doing differently from R CMD Sweave and R CMD build/install when it comes to vignette building, and is there anything I can do to make R CMD check respect knitr's 'eval' specification? Note that if I use eval=FALSE, R CMD check will respect it and everything is fine; the problem only occurs if I try selective evaluation of a chunk.
I have added vignette engines with the suffix _notangle in the knitr development version 1.6.2. For the original vignette engine knitr::foo, you can use the new engine knitr::foo_notangle to disable tangle (e.g. knitr::knitr_notangle, knitr::rmarkdown_notangle, ...).
If you do not want to wait for the next version of knitr to be on CRAN (which might take a while), you can certainly register a package vignette engine by yourself. Hint: you can make use of existing engines in tools::vignetteEngine(package = 'knitr') so you do not have to completely redefine the knitr vignette engines.
It seems that the issue is more nuanced than I originally thought, so this might not get resolved anytime soon. my workaround is to:
manually build the vignettes using R CMD Sweave
Copy the HTML outputs to inst/doc
Delete the vignettes folder (or add entries to .Rbuildignore--thanks #Ben!)
Build and check
It's not ideal, but right now it looks like the only way for my package to get through CRAN checks.
From the Writing R Extensions Manual, I read that
As from R 2.14.0 the preferred location for the Sweave sources is the
subdirectory vignettes of the source packages, but for compatibility
with earlier versions of R, vignette sources will be looked for in
inst/doc if vignettes does not exist.
However, when I create a vignettes subdirectory of the package source, when I run devtools::check() or R CMD check I get a warning for Package vignette(s) without corresponding PDF. If I put the vignette (.Rnw and .pdf) in inst/doc the check completes without complaints. I tried looking in my library at installed packaged and did not see any directories named vignettes. Should I still use the deprecated location?
You put the .Rnw sources in vignettes/ as you did, but you missed out a critical step; don't check the source tree. The expected workflow is to build the source tarball and then check that tarball. Building the tarball will create the vignette PDF.
R CMD build ../foo/pkg
R CMD check ./pkg-0.4.tar.gz
for example will build a source package tarball from the sources in ../foo/pkg creating the .tar.gz package in the current directory with the package name and version appended. Then you run R CMD check on that source package.
If you want your vignette built for you put it in vignettes/ and build the source package. At some future date, R Core may remove the ability to build vignettes from inst/doc so go with the advised location now and avoid check the sources directly.
I had a hard time interpreting this too.
I believe the intention is that you should put the .Rnw file in vignettes/ and the PDF (suitably compacted) in inst/doc/, which technically agrees with the documentation if you read carefully enough. (That is, it says the sources should go in vignettes/. I don't see where it says in so many words that you ought to put the corresponding PDF in inst/doc/, but it doesn't not say it, and that interpretation seems to make R CMD check happy ...)
The resolution is in #GavinSimpson's answer (i.e. one is expected to build the tarball and then check it, rather than checking the source directory itself). (My two cents is that it might be best if R-core officially deprecated (and eventually removed) direct source checking rather than confusing all of us groundlings ...)