From e1dd71b6bd2bfb2cffe31eed81bc98880cafae86 Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Thu, 5 Jun 2025 15:06:32 -0400 Subject: [PATCH] add mentions of quarto vignettes --- documentation.Rmd | 53 +++++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/documentation.Rmd b/documentation.Rmd index 41362a8..5714ab7 100644 --- a/documentation.Rmd +++ b/documentation.Rmd @@ -24,7 +24,7 @@ it is always possible to extend existing classes. ## Vignettes {#vignettes} A vignette demonstrates how to accomplish non-trivial tasks embodying the core -functionality of your package. There are two common types of vignettes. +functionality of your package. There are three types of vignettes. * (Recommended) An *R markdown* vignette is similar to a *Sweave* vignette, but uses [markdown](http://daringfireball.net/projects/markdown/) instead of @@ -34,11 +34,20 @@ functionality of your package. There are two common types of vignettes. vignettes][CRAN vigs] for technical details. See the `r BiocStyle::Biocpkg("BiocStyle")` package for a convenient way to use common macros and a standard _Bioconductor_ style vignette. - -* A *Sweave* vignette is an `.Rnw` file that contains $\LaTeX$ and chunks of code. The code chunk starts with a line + +* Quarto is a new format for vignettes that uses the + [Quarto](https://quarto.org/) system. It is similar to R Markdown but offers + more advanced features and flexibility. Similar to R Markdown, Quarto + vignettes can be rendered to various formats, including HTML and PDF, and are + suitable for multi-language documentation needs. Note that an installation + of the `quarto` command line tool is required to build Quarto vignettes. + +* A *Sweave* vignette is an `.Rnw` file that contains $\LaTeX$ and chunks of + code. The code chunk starts with a line `<<>>=`, and ends with `@`. Each chunk is evaluated during `R CMD build`, - prior to $\LaTeX$ compilation to a PDF document. + prior to $\LaTeX$ compilation to a PDF document. Note that this format + requires $\LaTeX$ dependencies for rendering that are not be available in + standard _Bioconductor_ containers. A vignette provides reproducibility: the vignette produces the same results as copying the corresponding commands into an @@ -49,21 +58,20 @@ markdown) undermine the benefit of vignettes and are generally **not allowed**; exceptions can be made with proper justification and are at the discretion of [_Bioconductor_ reviewers][reviewer-list]. -All packages are required to have at least one Rmd or Rnw vignette. Vignettes go -in the `vignettes/` directory of the package. Vignettes are often used as -standalone documents, so best practices are to include an informative title, the -primary author of the vignette, the last modification date of the vignette, and -a link to the package landing page. We encourage the use of `r -BiocStyle::Biocpkg("BiocStyle")` for formatting with `html_document` as -rendering target. Something like the following in the vignette will accomplish -the above suggestion: +All packages are required to have at least one Rmd, qmd, or Rnw vignette. +Vignettes go in the `vignettes/` directory of the package. Vignettes are often +used as standalone documents, so best practices are to include an informative +title, the primary author of the vignette, the last modification date of the +vignette, and a link to the package landing page. We encourage the use of +`r BiocStyle::Biocpkg("BiocStyle")` with `html_document` as the rendering +function. For example, in an R Markdown vignette one can use the following +specification in the yaml front matter: -``` +```yaml output: BiocStyle::html_document: toc: true toc_depth: 2 - ``` If you want to write more than one vignette, you may want to control @@ -76,10 +84,10 @@ e.g. using numbers `1-9`, if you have a single digit number of vignettes, or `01-99` if you have ten or more vignettes. For example, the first vignette could specify in the header: -``` +```yaml vignette: > %\VignetteEngine{knitr::rmarkdown} - %\VignetteIndexEntry{1. Quick start to MyPackage} + %\VignetteIndexEntry{1. Quick Start: An Introduction} %\VignetteEncoding{UTF-8} ``` @@ -126,12 +134,11 @@ Include a section with the `SessionInfo()` at the end of the vignette. ### `vignettes/` directory and intermediate files -Only the source vignette file (`.Rnw` or `.Rmd`) and any necessary static images -should be in the vignette directory. No intermediate files should be -present. This include complete processed vignette products as well; the vignette -should be created through the `R CMD build` of a package. To include other types -of documentation please use the `inst/doc` or other appropriately named `inst` -directory. +Only the source vignette file (`.Rnw`, `.qmd`, or `.Rmd`) and any necessary +static images should be in the `vignettes/` directory. No intermediate files +should be present, including vignette products. Vignettes are created through +by running `R CMD build` on a package. To include other types of documentation +please use the `inst/doc` or other appropriately named `inst` directory. ### References