Re: [R-pkg-devel] [Rd] static html vignette
I may add two cents on that as we recently made this change in data.table. Using markdown package instead of rmarkdown as a vignette engine reduced burden caused by extra dependencies tremendously. Moreover it made package to not even need c++ compiler, as knitr and markdown both (and their recursive deps) are pure C with no C++. Gains were huge. Deps installation time from 12min to 30sec. CI pipeline compute minutes saving around 100min on a single workflow. But there is even a better news (so be sure to upvote), that knitr may not be required to render Rmd at all in near future. For details see https://github.com/rstudio/markdown/issues/109 On Thu, Jan 4, 2024, 22:27 Adrian Dușa wrote: > On Thu, Jan 4, 2024 at 10:44 PM Uwe Ligges < > lig...@statistik.tu-dortmund.de> > wrote: > > > On 04.01.2024 21:23, Duncan Murdoch wrote:[...] > > > 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. > > > > I see... then I must have tested with dependencies = TRUE thinking this > refers to hard dependencies (one more reason to read the documentation > properly). > > Thank you, > Adrian > > [[alternative HTML version deleted]] > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel > [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] [Rd] static html vignette
On Thu, Jan 4, 2024 at 10:44 PM Uwe Ligges wrote: > On 04.01.2024 21:23, Duncan Murdoch wrote:[...] > > 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. > I see... then I must have tested with dependencies = TRUE thinking this refers to hard dependencies (one more reason to read the documentation properly). Thank you, Adrian [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] [Rd] static html vignette
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
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
> > wrote:
> > >
> > >> On Thu, 4 Jan 2024 11:57:15 +0200
> > >> Adrian Dușa 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@r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-package-devel
> __
> R-package-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] [Rd] static html vignette
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
wrote:
>
>> On Thu, 4 Jan 2024 11:57:15 +0200
>> Adrian Dușa 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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] [Rd] static html vignette
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
wrote:
>
>> On Thu, 4 Jan 2024 11:57:15 +0200
>> Adrian Dușa 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.
Duncan Murdoch
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] [Rd] static html vignette
(Moved here following Ivan's suggestion)
On Thu, Jan 4, 2024 at 12:55 PM Ivan Krylov wrote:
> On Thu, 4 Jan 2024 11:57:15 +0200
> Adrian Dușa 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]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
