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 ...)
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.
I would like to include static vignettes in my R package that will show up for users using the R function browseVignettes().
I need the vignettes to be static because the vignettes take too long to build, causing me to fail CRAN checks on win-builder if they are included dynamically.
The package R.rsp seems to provide exactly what I want; described here: https://cran.r-project.org/web/packages/R.rsp/vignettes/R_packages-Static_PDF_and_HTML_vignettes.pdf .
I followed the instructions from R.rsp. I have a vignettes folder that contains a .html file with a corresponding .Rmd file and a .html.asis file, as directed. I also have the appropriate code in the DESCRIPTION file. With these settings, I pass CRAN tests on win-builder, travis, etc. However, when I download the package from github, it says that there are no vignettes associated with the package. Am I missing something about the R.rsp package? Is this capability outdated? Do I need to copy the built vignettes from the Vignettes folder into an inst/doc folder? (I have seen conflicting information about vignettes folder vs inst/doc folder).
Is using something like R.rsp::asis the best way to include vignettes that take too long to build to include dynamically? Another method that I have seen is to include the vignettes folder in .Rbuildignore, and then include a note in the README file telling users that they can build the vignettes separately from github in order to view them. I am also considering including links in the README to external vignettes. Is this a better approach? Which might CRAN prefer?
Add build_vignettes=TRUE to your install_github call.
I am building an R package.
I have an rmarkdown file at vignettes/mydoc.Rmd.
Using devtools::build_vignettes() results in files appearing at inst/doc.
No warnings or errors appear when I use R CMD build ..
However, when I use vignette() from within R, I do not see any vignette for the package.
My DESCRIPTION file includes:
Suggests: knitr,
rmarkdown,
VignetteBuilder: knitr
It's not clear how/if you're installing in between steps. I'll quote from Hadley's R Packages website, the Vignettes chapter, mostly from the Development Cycle section:
To create your first vignette, run:
devtools::use_vignette("my-vignette")
This will:
Create a vignettes/ directory.
Add the necessary dependencies to DESCRIPTION (i.e. it adds knitr to the Suggests and VignetteBuilder fields).
Draft a vignette, vignettes/my-vignette.Rmd.
The above can be done manually or via the use_vignette() command, but it does need to be done.
After authoring your vignette, it will need to be built.
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. RStudio’s "Build & reload" does not build vignettes to save time. Similarly, devtools::install_github() (and friends) will not build vignettes by default because they’re time consuming and may require additional packages. You can force building with devtools::install_github(build_vignettes = TRUE). This will also install all suggested packages.
I believe that devtools::install() will include any vignettes that are already built, the extra argument is only needed if you want rebuild them at the time of installation.
R CMD BUILD makes a tarball, it doesn't modify your development directories, and R CMD INSTALL installs the package in your library, it also doesn't modify your development directories.
For development you can use just devtools::install(..., build_vignettes = T) when you want to rebuild vignettes and install a package.
You really only need to build the package itself (generate zip or tarball depending on your system) when you're ready to release to CRAN. At that point, I'd use devtools::build(..., vignettes = T) as a wrapper for R CMD BUILD, but that's just a preference.
I've been experiencing very erratic behaviour with
R CMD build myPackage
R CMD INSTALL myPackage
sometimes this installs the vignettes, and sometimes not.
devtools::install(build_vignettes = TRUE) seems like a more robust alternative. It also has the advantage of offering to update any outdated packages involved in the installation.
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.
Problem:
C:\>Rcmd.exe INSTALL --build --library=C:/Users/local_aphalo/Documents/R/win-library/3.0 photobiology
C:\>Rcmd.exe INSTALL --build --library=C:/Users/local_aphalo/Documents/R/win-library/3.0 photobiology_0.2.6.tar.gz
The first command (as used by RStudio) builds a ZIP file that is missing the vignettes.
The second command builds a ZIP that includes the vignettes.
Using R CMD instead of Rcmd.exe makes no difference. The .tar.gz was built immediately before attempting to build the .zip file, from exactly the same source files, from within RStudio (which uses Rcmd.exe build photobiology).
The vignettes are coded in .Snw files using knitr, documentation and NAMESPACE use ROxygen2. The problem happens on all of the packages that I have tried to build, but they are very similarly coded. Only one of them uses Rcpp.
When installing the package for use from within RStudio, installing from .tar.gz installs vignettes just fine. If installing from .zip, whether vignettes get installed or not, depends on whether the .zip files contains them or not (which depends on which of the two commands at the top of this message was used to build the .zip file).
I am using R 3.0.1, and also tried a couple of R 3.0.1 patched builds a few days back. I am mostly using Windows 7 (both 32 bit, and 64 bit), I tried once under Ubuntu 64bit, and the problem is reproducible. I first noticed the problem when using RStudio (0.97 and 0.98) and posted a message in the RStudio forum, but have received no answer in a couple of weeks. I have found at least another relatively old post about this problem in the RStudio website forum, but it has not been answered. Today, I investigated a bit further, and the problem is clearly not related to RStudio, as I can reproduce it through the command line.
The question is: Is this behavior a feature? a bug? or I am missing just an option in the command used?
Of course, I can easily work around the problem at the command line by using the .tar.gz file to build the .zip file, but as I think the preferred way of building a package is by just supplying the package name as argument.
Thanks for any insights on the origin of this problem.
I think this is a feature:
if you're installing from source, vignettes are always built
if you're installing from a binary, they're not built, and will only be available if they were built when the binary was made
This approach means that you can distribute vignettes in binary packages to people who might not be able to build them from source.