Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Vignette engines for Quarto #57

Merged
merged 8 commits into from
Nov 3, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,15 @@ Imports:
rsconnect (>= 0.8.26),
rstudioapi,
utils,
tools,
yaml
Suggests:
knitr,
testthat (>= 3.1.0),
withr,
xfun
VignetteBuilder:
knitr
knitr, quarto
Config/testthat/edition: 3
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
Expand Down
1 change: 1 addition & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,6 @@ importFrom(rlang,is_interactive)
importFrom(rmarkdown,relative_to)
importFrom(rstudioapi,isAvailable)
importFrom(rstudioapi,viewer)
importFrom(tools,vignetteEngine)
importFrom(utils,browseURL)
importFrom(yaml,write_yaml)
24 changes: 24 additions & 0 deletions R/zzz.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@

#' Register engines to support Quarto vignettes
#' @importFrom tools vignetteEngine
#' @noRd
.onLoad <- function(libname, pkgname) { # args ignored
vignetteEngine(name = "pdf",
package = "quarto",
pattern = "[.]qmd$",
weave = function(file, ..., encoding = "UTF-8") {
quarto_render(file, ..., output_format = "pdf")
},
tangle = vignetteEngine("knitr::rmarkdown")$tangle,
aspell = vignetteEngine("knitr::rmarkdown")$aspell
)
Comment on lines +6 to +14
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding PDF vignette, we would like to put that on hold for now.

Quarto 1.4 has typst support, with typst CLI bundled in Quarto (https://quarto.org/docs/prerelease/1.4/typst.html) and this is a good way to produce PDF faster and more reliable than using LaTeX.

This could be safer on CRAN that to rely on the LaTeX installation. Do you have experience on CRAN to build LaTeX vignette ?
If we provice a pdf engine using LaTeX, we should probably tweak the default configuration so that for example latexmk auto install does no happen when running a vignette on CRAN. (I don't know if that is really allowed, and how LaTeX dependencies are handled on CRAN servers to build vignette).

So for now, I would only provide HTML vignette

Copy link
Contributor Author

@dcnorris dcnorris Oct 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have experience on CRAN to build LaTeX vignette ?

Not with Quarto, but certainly with Rmd. This vignette for my DTAT package serves to demonstrate the reproducibility of calculations for a peer-reviewed paper, e.g.:
https://cran.r-project.org/web/packages/DTAT/vignettes/dtat.pdf

I would tend to discourage gratuitous FUD here about building LaTeX stuff on CRAN. I don't recall myself ever having to 'downgrade' a PDF vignette to HTML for any technical reason.


See also https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Writing-package-vignettes.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry if my tone was not the good one. (sometimes non native english speaker catch me ... 😞)
I didn't mean to sound like I was doubtful about it working well. It was mainly question about what can really be done considering how quarto is working by default with quarto pdf engine

format: pdf require LaTeX and some packages. Pandoc's template and some quarto feature have requirement about LaTeX packages. By default, quarto will try to install missing LaTeX packages when rendering errors are found, and then retrigger a render. By "LaTeX installation", I mean which LaTeX extension are available or not. I don't think it is seen as good practice to automatically update tlmgr and install new missing LaTeX package. So I meant it was safer to opt-out this feature, or use PDF output produced by format: typst which is quicker to render.

I don't know the list of available LaTeX component from CTAN available on CRAN build machine to compare with Pandoc's and Quarto requirement. Maybe this is full texlive install available and so no problem ever.

However, as pointed out in the manual you rightly referenced, including the output in the source would make sure to LaTeX extension installation are needed. So that is a way to make sure it would work.

My concerns is preventing any problem with package building on CRAN because of how quarto works, and what impact building vignette with quarto could have. Maybe this is nothing to worry about.

Anyhow, I hope this clarifies my initial thoughts.

vignetteEngine(name = "html",
package = "quarto",
pattern = "[.]qmd$",
weave = function(file, ..., encoding = "UTF-8") {
quarto_render(file, ..., output_format = "html")
},
dcnorris marked this conversation as resolved.
Show resolved Hide resolved
tangle = vignetteEngine("knitr::rmarkdown")$tangle,
aspell = vignetteEngine("knitr::rmarkdown")$aspell
)
}
36 changes: 36 additions & 0 deletions vignettes/hello.qmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: "Quarto Vignettes"
format:
pdf:
toc: false
html:
toc: true
vignette: >
%\VignetteIndexEntry{Vignettes}
%\VignetteEngine{quarto::pdf}
%\VignetteEncoding{UTF-8}
---

## Hello Vignette World!

This is an example Quarto vignette, demonstrating how the **quarto** package can let you write package vignettes in Quarto.

## Two Vignette Engines

The **quarto** package registers 2 vignette engines, `quarto::pdf` and `quarto::html`. Either of these may be selected in a Quarto vignette's YAML header. For example, this vignette's header reads:
```yaml
---
title: "Quarto Vignettes"
format:
pdf:
toc: false
html:
toc: true
vignette: >
%\VignetteIndexEntry{Vignettes}
%\VignetteEngine{quarto::pdf}
%\VignetteEncoding{UTF-8}
---
```

Consequently, a PDF version of this vignette is built.