Optimal workflows for package vignettes - R-hub blog

[utterances-bot]

Optimal workflows for package vignettes - R-hub blog

https://blog.r-hub.io/2020/06/03/vignettes/

[lucharo]

Hello and thank you for the great article, I am building vignettes for my package. After looking around the internet and your blogpost, I am still confused about the differences and relationship between vignettes/, inst/doc/ and doc/. When I run build_vignettes(), I get an .R file and a .html file in the vignettes/ folder and the doc/ folder moves outside of inst/ and remains empty. Additionally I get the following message when running build_vignettes():

Error in if (dir_exists(path %||% "") && is_in_proj(path)) { : 
  missing value where TRUE/FALSE needed

Though I have no idea where it is coming from (Upon some more search, the error seems to come from the use_this package, see link to source code) All help is appreciated

[maelle]

👋 @lc5415 Why do you run build_vignettes() by the way?

[maelle]

I am asking because I never run it and https://r-pkgs.org/vignettes.html#vignette-workflow-2 also recommends building the whole package instead.

[lucharo]

Hello @maelle thanks, for your message. I guess I run build vignettes to isolate the process and check whether my vignettes could be built on their own. Thanks for pointing me to the book, I was struggling to find the right resources regarding vignettes. The trouble I pointed at in the previous comment seemed to disappear, on its own though. If devtools::install_github() does not build vignettes by default, what is the best way to distribute vignettes, pkgdown? Otherwise, do CRAN packages installed through install.packages() have their vignettes built?

[maelle]

RStudio Community thread https://community.rstudio.com/t/difference-between-inst-doc-and-doc/83836/3

[aammd]

hi @maelle ! I really like this post! I was wondering if you know of any way to make files of the type .Rmd.orig look and act like "real" .Rmd files during development?

[maelle]

No, that'd be nice indeed. Wouldn't this be a good feature request for the RStudio IDE ( no idea how this would work with other editors)? If you open one please tag me and I'll go 👍 it 😀

[maelle]

It was suggested (thanks @jeroen) that instead, one should tweak the workflow to call the original vignette .Rmd but in another path. This way it's actually an Rmd.

[maelle]

it'd probably be wise to have their filenames start with an underscore cf https://pkgdown.r-lib.org/reference/build_articles.html so that pkgdown will ignore them

[KZARCA]

Thank you so much Maëlle, I could't find how to limit the computation time in my vignettes!