R package - vignettes

I am a little confused as to why there are multiple possible locations for "vignettes" in an R package. I don't understand which locations are used for what and when. For example:

devtools::use_vignettes()

creates a vignettes folder under the root of the package

devtools::build_vignettes() 

creates a inst/doc folder that gets promoted to the root at build

pkgdown::build_site()

creates a docs folder.

As background:I have read H.Wickhams R packages book and I have created several packages using the first option and all things have behaved well. I would have users install from github using:

devtools::install_github(pkg,build_vignettes=TRUE)

Now, I have just started to contribute in the joint development of a package in which the first and third option have been used. I have noticed that the .rmd file in the vignettes folder is the same as the index.html file in the docs folder. Does pkgdown copy from the vignettes folder?

Also for this package when i install from github (with build_vignettes=TRUE) i get an error saying installation failed because the doc/index.html path couldn't be found. Now why would that happen?

2 Likes

Welcome to the RStudio Community, @andyb!

This is used to create the "infrastructure" for you to create and edit your vignettes.

The devtools help file describes its purpose as:

Builds package vignettes using the same algorithm that R CMD build does.

Basically, this creates the vignette files as they would be created when the package as built for CRAN so that they can be read online. The files that are built are based on what is stored in the vignettes/ directory.

This is particularly useful if you are creating your own package website. The docs/ folder can be used as a basis to create a website using GitHub pages.

The docs/index.html file should reflect one of several files in a package, either index.Rmd or README.Rmd (there are a couple of other options, but these are the most common).

The "Get Started" article is based on the vignette that is named the same as your package. All the other articles you see on a pkgdown website are built from the other vignettes based on what is stored in the vignettes/ directory.

Can you link to the package?

2 Likes

Thanks Chris,
So what i am understanding from your response in that a good practice should be to develop the .rmd files in the vignettes folder. pkgdown and devtools::build_vignettes() will use these to create documentation. Does that seem fair?

the package can be found here: removed ecodata
thanks

Precisely!

For what it is worth, I don't use devtools::build_vignettes() at all. I use devtools::check() (which includes an evaluation of the vignette files and will catch some issues), and then use pkgdown::build_site() to get previews of how the vignette renders. I'd be curious to know what other developers' practices are with devtools::build_vignettes(), particularly now that pkgdown use is increasingly the norm.

Took a quick look at your package (beautiful hex sticker, by the way), and the one thing that stood out to me is that you are ignoring the inst/ folder in your .Rbuildignore file. That isn't typical, and my guess is that when you try and build your vignettes, it errors because the inst/ folder is a part of that process.

2 Likes

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.