too many steps to browseVignettes for in-progress package

setgree commented 3 weeks ago

I am working on a package which is primarily vignette-based, available at https://github.com/setgree/PaluckMetaSOP.

My local branch and the above repo are synced.

I want to periodically see how my vignettes look overall, and it is a lot of steps to remember how to browse them.

> browseVignettes('PaluckMetaSOP')
No vignettes found by browseVignettes("PaluckMetaSOP")

so then I remember to do devtools::install(build_vignettes = T), and once it's built, vignettes work.

Then I make some changes to my packages, and I reinstall things. Let's say I forget the build_vignettes flag.

> devtools::install()
── R CMD build ────────────────────────────────────────────────────────────────────────────────────────
✔  checking for file ‘/Users/setgree/Dropbox/research/PaluckMetaSOP/package/DESCRIPTION’ ...
─  preparing ‘PaluckMetaSOP’: (2.4s)
✔  checking DESCRIPTION meta-information
─  checking for LF line-endings in source and make files and shell scripts
─  checking for empty or unneeded directories
─  building ‘PaluckMetaSOP_0.3.tar.gz’

Running /Library/Frameworks/R.framework/Resources/bin/R CMD INSTALL \
  /var/folders/dg/mqmjyqjd4hz56xbfbzfj491r0000gn/T//RtmpBrXbDD/PaluckMetaSOP_0.3.tar.gz \
  --install-tests 
* installing to library ‘/Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library’
* installing *source* package ‘PaluckMetaSOP’ ...
** using staged installation
** R
** data
*** moving datasets to lazyload DB
** inst
** byte-compile and prepare package for lazy loading
** help
*** installing help indices
** building package indices
** installing vignettes
** testing if installed package can be loaded from temporary location
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (PaluckMetaSOP)
> browseVignettes('PaluckMetaSOP')
No vignettes found by browseVignettes("PaluckMetaSOP")

Ok, so now I am thinking: what was that command again? Was it build with vignettes =T ? No I'm afraid that doesn't work

> devtools::build(vignettes = T)
── R CMD build ────────────────────────────────────────────────────────────────────────────────────────
✔  checking for file ‘/Users/setgree/Dropbox/research/PaluckMetaSOP/package/DESCRIPTION’ ...
─  preparing ‘PaluckMetaSOP’: (1.9s)
✔  checking DESCRIPTION meta-information ...
─  installing the package to build vignettes
✔  creating vignettes (20.6s)
─  checking for LF line-endings in source and make files and shell scripts (371ms)
─  checking for empty or unneeded directories
─  building ‘PaluckMetaSOP_0.3.tar.gz’

[1] "/Users/setgree/Dropbox/research/PaluckMetaSOP/PaluckMetaSOP_0.3.tar.gz"
> browseVignettes('PaluckMetaSOP')
No vignettes found by browseVignettes("PaluckMetaSOP")

(Confused why vignettes = T doesn't make vignettes available?)

devtools::check() does the trick. I guess that's what I should be running every time (though it takes about 90 seconds per run).

But is there is a way to make this easier? The main thing would be, if I have vignettes available, I don't see why they become no longer available when I run build or install.

Thanks!

jennybc commented 3 weeks ago

This is just plain awkward. But I've put all of my best advice here:

https://r-pkgs.org/vignettes.html#sec-vignettes-workflow-writing

Various solutions have been tried to the vignette-building workflow over the years and I honestly think many of them do more harm than good, which is explore more here:

It is tempting to fight this (and many have tried), but based on years of experience and discussion, the devtools philosophy is to accept this reality.

https://r-pkgs.org/vignettes.html#sec-vignettes-how-built

I still currently believe there is no obvious call-to-action to do something new in the (devtools) tooling.

setgree commented 3 weeks ago

Ok, maybe we can start with something smaller then.

Confused why build(vignettes = T) doesn't make vignettes available?

the help page for this function says

For source packages: if FALSE, don't build PDF vignettes (--no-build-vignettes) or manual (--no-manual).

Who is this message written for? why is only the behavior for FALSE defined? Can these things be improved with R's average user in mind, who is not a professional software engineer?

jennybc commented 3 weeks ago

Confused why build(vignettes = T) doesn't make vignettes available?

Because build() just builds a package but doesn't actually install it?

https://devtools.r-lib.org/reference/build.html

Building converts a package source directory into a single bundled file.

setgree commented 2 weeks ago

Thank you, I was able to figure out what I need and get the steps in order.

Distinguishing between what build and install are actually aiming to do was helpful.

jennybc commented 2 weeks ago

Re: the different forms of an R package, this chapter might be helpful:

https://r-pkgs.org/structure.html

r-lib / usethis

too many steps to browseVignettes for in-progress package #1986