how to handle vignettes

venpopov / bmm

An R package for easy and flexible Bayesian Measurement Modeling

https://venpopov.github.io/bmm/

GNU General Public License v2.0

12 stars 3 forks source link

how to handle vignettes #83

Closed venpopov closed 6 months ago

venpopov commented 8 months ago

Their size is too large for CRAN because of the .rds fit files Installing them from github fails if you don't install all dependencies in Suggests

Options:

Prebuild them: https://ropensci.org/blog/2019/12/08/precompute-vignettes/
store the model fits elsewhere
make them all articles that exist only on the website (https://r-pkgs.org/vignettes.html#sec-vignettes-article)
make evaluation of chunks dependent on package availability (https://r-pkgs.org/vignettes.html#sec-vignettes-eval-option)
move the vignette dependencies from Suggests to Imports in DESCRIPTION

Other vignette tasks:

[ ] Organize the articles section by task, nested with models

GidonFrischkorn commented 7 months ago

I now have had some time looking into the different options. I think the easiest fix to getting the size of the package down is to make all vignettes articles and only have them on the webpage. My experience is that you would rarely work on code without an internet connection and even then, the documentation is quite detailed in my opinion. So, I would hope that users could work with that until they have internet again and then can have a look into the vignettes.

venpopov commented 7 months ago

Good with me. The code and examples are well documented. When trying out new packages I find it useful if there's a narrative introduction to their main features and use cases. Perhaps we make one general vignette "bmm-overview" that is precompiled and introduces people to the package. Like an expanded readme that goes over what measurement models are, why to use them, a few simple examples from the different functionalities. More breath than depth.

venpopov commented 7 months ago

This could be a rough shorter draft of what the general paper we want to write would be

GidonFrischkorn commented 7 months ago

I think having one "bmm-overview" vignette precompiled and shipped with the package is a good idea. And it would be a good start for the general paper we plan to write.

venpopov commented 7 months ago

Nothing this here not to forget:

[ ] Organize the articles section by task, nested with models