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

[Josiah Parry]

I understand that this doesn't actually *solve *your problem, but would
like to offer an alternative perspective.

I often find that vignettes may be most useful as an extended form of
documentation. If you have a pkgdown site, you can use
`usethis::use_article()` to create an article which will not be included as
part of the package itself but will be served in the documentation site of
the package. I don't think many people consume extended package
documentation through vignettes all that much but often prefer to rely on
the package website. Using the article format means that your package tests
on CRAN will not be subjected to any other packages used in the articles or
vignettes.

Cheers!

On Thu, Jan 4, 2024 at 3:44 PM Uwe Ligges <ligges using statistik.tu-dortmund.de>
wrote:

>
>
> On 04.01.2024 21:23, Duncan Murdoch wrote:
> > On 04/01/2024 11:43 a.m., Adrian Dușa wrote:
> >  > (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)
> > As far as I know, there is no package called Sweave, there's just the
> > Sweave() function in the utils package.>
> >  >
> >  >
> >  >> Still, you can ue 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.
> >  >
> > Users aren't forced to install "Suggests" packages.  That's a choice
> > they make.  The default for `install.packages()` is `dependencies = NA`,
> > which says to install hard dependencies (Imports, Depends, LinkingTo).
> > Users have to choose a non-default setting to include Suggests.
>
> Also note that the maintainer builds the vignette whe calling
> R CMD build
> CRAN checks whether the vignette can be build.
> If a user installs a package, the already produced vignette (on the
> maintainers machine by R CMD build) is instaled. There is no need for
> the user to install any extra package for being able to look at the
> vignettes.
>
> Best,
> Uwe Ligges
>
>
>
>
> >
> > Duncan Murdoch
> >
> > ______________________________________________
> > R-package-devel using r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-package-devel
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]