[R-pkg-devel] [Rd] static html vignette

[Adrian Dușa]

(Moved here following Ivan's suggestion)

On Thu, Jan 4, 2024 at 12:55 PM Ivan Krylov <krylov.r00t using gmail.com> wrote:

> On Thu, 4 Jan 2024 11:57:15 +0200
> Adrian Dușa <dusa.adrian using gmail.com> wrote:
>
> > I wonder if it would be possible to include an html static vignette.
>
> I would say that static vignettes are against the spirit of vignettes:
> the idea is to provide another layer of unit testing to the package by
> providing a deeper executable example than is possible with just Rd
> examples. I think that Bioconductor will even refuse a package with a
> vignette with no executable code in it.
>

I understand that perfectly, but for instance my package declared already
has over 800 tests and 100% code coverage. More unit testing in the
vignettes really strikes as unnecessary.

One other reason to use a static vignette, in my case, is that package
Sweave is not available for my version of R (on MacOS, M2 version)



> Still, you can use the R.rsp package to provide static vignettes in
> both PDF and HTML formats:
>
> https://cran.r-project.org/package=R.rsp/vignettes/R_packages-Static_PDF_and_HTML_vignettes.pdf
>
> This will add 6 packages to your total Suggests budget:
>
> setdiff(
>  unlist(package_dependencies('R.rsp', recursive=TRUE)),
>  unlist(standard_package_names())
> )
> # [1] "R.methodsS3" "R.oo"        "R.utils"     "R.cache"     "digest"


Yes indeed, I know about R.rsp.
To me at least, zero dependency means that users install that package and
that package alone, the reason for which I am now looking for static
(preferably html) vignettes.

I guess another question is why should the "Suggests" packages need to be
installed by end users. I understand CRAN checks need to make sure the
Vignettes can be processed and the code inside runs fine (just like the
examples in the Rd files) but it is very unlikely that end-users will want
to compile the vignettes themselves.

From my own experience of almost 20 years of using R, I never-ever build
the vignettes of a certain package because it is much simpler to read them
on CRAN. I wonder, then, why are end users forced to install
Vignette-building "Suggests" packages (with long dependency chains) when
they practically never do that.

Life would be much simpler if the Suggests packages would not be
(automatically) installed, or if CRAN provided a way to include static
Vignettes to avoid the heavy dependencies of building them.

Best regards,
Adrian

	[[alternative HTML version deleted]]