use litedown for rendering vignettes

.dev/CRAN_Release.cmd

@@ -323,7 +323,7 @@ Rdevel-strict-[gcc|clang] CMD check data.table_1.16.99.tar.gz
 Rdevel-strict-[gcc|clang]
 isTRUE(.Machine$sizeof.longdouble==0)  # check noLD is being tested
 options(repos = "http://cloud.r-project.org")
-install.packages(c("bit64", "bit", "R.utils", "xts", "zoo", "yaml", "knitr", "markdown"),
+install.packages(c("bit64", "bit", "R.utils", "xts", "zoo", "yaml", "litedown"),
                  Ncpus=4)
 # Issue #5491 showed that CRAN is running UBSAN on .Rd examples which found an error so we now run full R CMD check
 q("no")

.github/workflows/R-CMD-check-occasional.yaml

@@ -111,7 +111,7 @@ jobs:
             TEST_DATA_TABLE_WITH_OTHER_PACKAGES=as.character(run_other)
           )
 
-          do_vignettes = requireNamespace("knitr", quietly=TRUE)
+          do_vignettes = requireNamespace("litedown", quietly=TRUE)
 
           build_args = NULL
           check_args = c("--no-manual", "--as-cran")

DESCRIPTION

@@ -3,12 +3,13 @@ Version: 1.18.99
 Title: Extension of `data.frame`
 Depends: R (>= 3.5.0)
 Imports: methods
-Suggests: bit64 (>= 4.0.0), bit (>= 4.0.4), R.utils (>= 2.13.0), xts, zoo (>= 1.8-1), yaml, knitr, markdown
+Suggests: bit64 (>= 4.0.0), bit (>= 4.0.4), R.utils, xts, zoo (>= 1.8-1), yaml, litedown
+Enhances: knitr, xfun
 Description: Fast aggregation of large data (e.g. 100GB in RAM), fast ordered joins, fast add/modify/delete of columns by group using no copies at all, list columns, friendly and fast character-separated-value read/write. Offers a natural and flexible syntax, for faster development.
 License: MPL-2.0 | file LICENSE
 URL: https://r-datatable.com, https://Rdatatable.gitlab.io/data.table, https://github.com/Rdatatable/data.table
 BugReports: https://github.com/Rdatatable/data.table/issues
-VignetteBuilder: knitr
+VignetteBuilder: litedown
 Encoding: UTF-8
 ByteCompile: TRUE
 Authors@R: c(

NAMESPACE

@@ -114,7 +114,10 @@ if (getRversion() >= "4.0.0") {
   # version of R (and that is checked in .onLoad with error if not).
   export(.rbind.data.table) # only export in R<4.0.0 where it is still used; R-devel now detects it is missing doc, #5600
 }
-if (getRversion() >= "3.6.0") S3method(knitr::knit_print, data.table) # else manual delayed registration from the onLoad hook
+if (getRversion() >= "3.6.0") {
+  S3method(knitr::knit_print, data.table)
+  S3method(xfun::record_print, data.table)
+} # else manual delayed registration from the onLoad hook
 S3method(dim, data.table)
 S3method(dimnames, data.table)
 S3method("dimnames<-", data.table)

NEWS.md

@@ -10,6 +10,8 @@
 
 2. pydatatable compatibility layer in `fread()` and `fwrite()` has been removed, [#7069](https://github.com/Rdatatable/data.table/issues/7069). Thanks @badasahog for the report and the PR.
 
+3. Vignettes are now built using `litedown` instead of `knitr`, [#6394](https://github.com/Rdatatable/data.table/issues/6394). Thanks @jangorecki for the suggestion and @ben-schwen and @aitap for the implementation.
+
 ### BUG FIXES
 
 1. `fread()` with `skip=0` and `(header=TRUE|FALSE)` no longer skips the first row when it has fewer fields than subsequent rows, [#7463](https://github.com/Rdatatable/data.table/issues/7463). Thanks @emayerhofer for the report and @ben-schwen for the fix.

R/onLoad.R

@@ -67,6 +67,12 @@
     setHook(packageEvent("knitr", "onLoad"), function(...) {
       registerS3method("knit_print", "data.table", knit_print.data.table, envir = asNamespace("knitr"))
     })
+    if (isNamespaceLoaded("xfun")) {
+      registerS3method("record_print", "data.table", record_print.data.table, envir = asNamespace("xfun"))
+    }
+    setHook(packageEvent("xfun", "onLoad"), function(...) {
+      registerS3method("record_print", "data.table", record_print.data.table, envir = asNamespace("xfun"))
+    })
   }
 
   # Set options for the speed boost in v1.8.0 by avoiding 'default' arg of getOption(,default=)

R/print.data.table.R

@@ -294,7 +294,13 @@ trunc_cols_message = function(not_printed, abbs, class, col.names){
 }
 
 # Maybe add a method for repr::repr_text.  See https://github.com/Rdatatable/data.table/issues/933#issuecomment-220237965
+# nocov start
 knit_print.data.table = function(x, ...) {
   if (!shouldPrint(x)) return(invisible(x))
   NextMethod()
 }
+record_print.data.table = function(x, ...) {
+  if (!shouldPrint(x)) return(character())
+  NextMethod()
+}
+# nocov end

inst/tests/other.Rraw

@@ -182,6 +182,9 @@ if (loaded[["knitr"]]) {
   # Which is fine and works thanks to cedta().
   DT = data.table(x=1, y=2)
   test(11, kable(DT), output="x.*y.*1.*2")
+  invisible(knit(testDir("knitr.Rmd"), quiet=TRUE))
+  cat(readLines("knitr.md"), sep="\n")
+  invisible(file.remove("knitr.md"))
 }
 
 if (loaded[["parallel"]]) {

tests/litedown.R

@@ -0,0 +1,15 @@
+if (!suppressPackageStartupMessages(requireNamespace("litedown", quietly = TRUE))) {
+  cat(readLines("litedown.Rout.mock", warn = FALSE), sep = "\n")
+  q("no")
+}
+
+# Load litedown and render the Rmd file
+library(litedown)
+litedown::reactor(comment="# ", print=xfun::record_print)
+invisible(litedown::fuse("litedown.Rmd", output = "litedown.md"))
+
+# Print the rendered markdown content
+cat(readLines("litedown.md"), sep = "\n")
+
+# Clean up
+invisible(file.remove("litedown.md"))

tests/knitr.Rmd → tests/litedown.Rmd

@@ -1,4 +1,4 @@
-```{r test_id, message=FALSE, results="show", echo=TRUE, warning=FALSE}
+```{r, test_id, message=FALSE, results="show", echo=TRUE, warning=FALSE}
 require(data.table)              # print?
 DT = data.table(x=1:3, y=4:6)    # no
 DT                               # yes

vignettes/_translation_links.R

@@ -2,7 +2,7 @@
 # idea is to look like 'Other languages: en | fr | de'
 .write.translation.links <- function(fmt) {
     url = "https://rdatatable.gitlab.io/data.table/articles"
-    path = dirname(knitr::current_input(TRUE))
+    path = dirname(litedown::get_context("input"))
     if (basename(path) == "vignettes") {
       lang = "en"
     } else {
@@ -11,13 +11,13 @@
     }
     translation = dir(path,
       recursive = TRUE,
-      pattern = glob2rx(knitr::current_input(FALSE))
+      pattern = glob2rx(litedown::get_context("input"))
     )
     transl_lang = ifelse(dirname(translation) == ".", "en", dirname(translation))
     block = if (!all(transl_lang == lang)) {
       linked_transl = sprintf("[%s](%s)", transl_lang, file.path(url, sub("(?i)\\.Rmd$", ".html", translation)))
       linked_transl[transl_lang == lang] = lang
       sprintf(fmt, paste(linked_transl, collapse = " | "))
     } else ""
-    knitr::asis_output(block)
+    litedown::raw_text(block)
 }

vignettes/datatable-benchmarking.Rmd

@@ -1,17 +1,22 @@
 ---
 title: "Benchmarking data.table"
-date: "`r Sys.Date()`"
+date: "`{r} Sys.Date()`"
 output:
-  markdown::html_format:
+  litedown::html_format:
     options:
       toc: true
       number_sections: true
 vignette: >
   %\VignetteIndexEntry{Benchmarking data.table}
-  %\VignetteEngine{knitr::knitr}
+  %\VignetteEngine{litedown::vignette}
   \usepackage[utf8]{inputenc}
 ---
 
+```{r, echo = FALSE, message = FALSE}
+library(data.table)
+litedown::reactor(comment = "# ")
+```
+
 <style>
 h2 {
     font-size: 20px;
@@ -25,9 +30,9 @@ h2 {
 }
 </style>
 
-```{r echo=FALSE, file='_translation_links.R'}
+```{r, echo=FALSE, file='_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`{r} .write.translation.links("Translations of this document are available in: %s")`
 
 This document is meant to guide on measuring performance of `data.table`. Single place to document best practices and traps to avoid.
 

vignettes/datatable-faq.Rmd

@@ -1,14 +1,14 @@
 ---
 title: "Frequently Asked Questions about data.table"
-date: "`r Sys.Date()`"
+date: "`{r} Sys.Date()`"
 output:
-  markdown::html_format:
+  litedown::html_format:
     options:
       toc: true
       number_sections: true
 vignette: >
   %\VignetteIndexEntry{Frequently Asked Questions about data.table}
-  %\VignetteEngine{knitr::knitr}
+  %\VignetteEngine{litedown::vignette}
   \usepackage[utf8]{inputenc}
 ---
 
@@ -26,18 +26,13 @@ h2 {
 }
 </style>
 
-```{r echo=FALSE, file='_translation_links.R'}
+```{r, echo=FALSE, file='_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`{r} .write.translation.links("Translations of this document are available in: %s")`
 
 ```{r, echo = FALSE, message = FALSE}
 library(data.table)
-knitr::opts_chunk$set(
-  comment = "#",
-    error = FALSE,
-     tidy = FALSE,
-    cache = FALSE,
- collapse = TRUE)
+litedown::reactor(comment = "# ")
 .old.th = setDTthreads(1)
 ```
 

vignettes/datatable-fread-and-fwrite.Rmd

@@ -5,7 +5,7 @@ output:
   markdown::html_format
 vignette: >
   %\VignetteIndexEntry{Fast Read and Fast Write}
-  %\VignetteEngine{knitr::knitr}
+  %\VignetteEngine{litedown::vignette}
   \usepackage[utf8]{inputenc}
 ---
 
@@ -15,12 +15,7 @@ vignette: >
 
 ```{r, echo = FALSE, message = FALSE}
 require(data.table)
-knitr::opts_chunk$set(
-  comment = "#",
-    error = FALSE,
-     tidy = FALSE,
-    cache = FALSE,
- collapse = TRUE)
+litedown::reactor(comment = "# ")
 .old.th = setDTthreads(1)
 ```
 

vignettes/datatable-importing.Rmd

@@ -1,23 +1,28 @@
 ---
 title: "Importing data.table"
-date: "`r Sys.Date()`"
+date: "`{r} Sys.Date()`"
 output:
-  markdown::html_format
+  litedown::html_format
 vignette: >
   %\VignetteIndexEntry{Importing data.table}
-  %\VignetteEngine{knitr::knitr}
+  %\VignetteEngine{litedown::vignette}
   \usepackage[utf8]{inputenc}
 ---
 
+```{r, echo = FALSE, message = FALSE}
+litedown::reactor(comment = "# ")
+.old.th = data.table::setDTthreads(1)
+```
+
 <style>
 h2 {
     font-size: 20px;
 }
 </style>
 
-```{r echo=FALSE, file='_translation_links.R'}
+```{r, echo=FALSE, file='_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`{r} .write.translation.links("Translations of this document are available in: %s")`
 
 This document is focused on using `data.table` as a dependency in other R packages. If you are interested in using `data.table` C code from a non-R application, or in calling its C functions directly, jump to the [last section](#non-r-api) of this vignette.
 
@@ -41,7 +46,7 @@ The next thing is to define what content of `data.table` your package is using.
 
 You may also want to use just a subset of `data.table` functions; for example, some packages may simply make use of `data.table`'s high-performance CSV reader and writer, for which you can add `importFrom(data.table, fread, fwrite)` in your `NAMESPACE` file. It is also possible to import all functions from a package _excluding_ particular ones using `import(data.table, except=c(fread, fwrite))`.
 
-Be sure to read also the note about non-standard evaluation in `data.table` in [the section on "undefined globals"](#globals)
+Be sure to read also the note about non-standard evaluation in `data.table` in [the section on "undefined globals"](#globals).
 
 ## Usage
 
@@ -283,3 +288,7 @@ result <- merge(dt, other_dt, by = "x")
 - **Namespace Management**: Only the functions your package explicitly imports are available, reducing the risk of function name clashes.
 - **Cleaner Package Loading**: Your package's dependencies are not attached to the search path, making the loading process cleaner and potentially faster.
 - **Easier Maintenance**: It simplifies maintenance tasks as upstream dependencies' APIs evolve. Depending too much on `Depends` can lead to conflicts and compatibility issues over time.
+
+```{r, echo = FALSE, message = FALSE}
+data.table::setDTthreads(.old.th)
+```