在构建和重新加载R包时显示vignettes链接

Question

I have created a vigentte folder for an R package I am developing by running the code devtools::use_vignette("my-vignette") . I am using Rmarkdown and knitr packages.

When I build & reload the package, I don't get a hyperlink for the title of the Rmarkdown file (which contains the long-form documentation of the package) in the documentation page of the package. I do get hyperlinks for the DESCRIPTION file of the package as well as the help pages of the documented functions but not the hyperlink that should direct people to the Rmarkdown document. I am wondering why and what should I do to get a hperlink for the long-form documentation of the package in a similar way that I get it for the help pages for the functions used in the package?

Answer 1

Daragh,

Can you provide more detail on the error you are seeing? If the code is posted on github or you have a specific error then we may be able to help further - if not then the best advice I can give is to check out Hadley Wickam's "R Packages" book online - it is a great reference:

http://r-pkgs.had.co.nz/

that will at least give you a good sense of how to build the vignettes.

http://r-pkgs.had.co.nz/vignettes.html

From the online book by Hadley Wickham referenced above...

---

CRAN notes

Note that since you build vignettes locally, CRAN only receives the html/pdf and the source code. However, CRAN does not re-build the vignette. It only checks that the code is runnable (by running it). This means that any packages used by the vignette must be declared in the DESCRIPTION. But this also means that you can use Rmarkdown (which uses pandoc) even though CRAN doesn't have pandoc installed.

Common problems:

The vignette builds interactively, but when checking, it fails with an error about a missing package that you know is installed. This means that you've forgotten to declare that dependency in the DESCRIPTION (usually it should go in Suggests).

Everything works interactively, but the vignette doesn't show up after you've installed the package. One of the following may have occurred. First, because RStudio's “build and reload” doesn't build vignettes, you may need to run devtools::install() instead. Next check:

• The directory is called vignettes/ and not vignette/.
• Check that you haven't inadvertently excluded the vignettes with .Rbuildignore
• Ensure you have the necessary vignette metadata.
• If you use error = TRUE, you must use purl = FALSE.

You'll need to watch the file size. If you include a lot of graphics, it's easy to create a very large file. There are no hard and fast rules, but if you have a very large vignette be prepared to either justify the file size, or to make it smaller.