diff --git a/.Rbuildignore b/.Rbuildignore index 46ab0604..e7d71237 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -9,7 +9,6 @@ README.qmd man-roxygen Makefile .quarto -vignettes/.*\.qmd$ vignettes/.*\.bib$ docs/ docs @@ -20,4 +19,5 @@ tinytable_assets ^man/figures/.*\\.png$ ^man/figures/gallery/.*\\.png$ sandbox/ +vignettes/tinytable_tutorial.qmd diff --git a/DESCRIPTION b/DESCRIPTION index d9411de0..f79a5a2e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -38,3 +38,5 @@ License: GPL (>= 3) Encoding: UTF-8 RoxygenNote: 7.3.2 Roxygen: list(markdown = TRUE) +VignetteBuilder: + quarto diff --git a/vignettes/alternatives.qmd b/vignettes/alternatives.qmd index 94e62c43..2dc8378a 100644 --- a/vignettes/alternatives.qmd +++ b/vignettes/alternatives.qmd @@ -1,7 +1,9 @@ --- title: "Alternative packages" -format: - html: default +vignette: > + %\VignetteIndexEntry{Other packages} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} --- ```{=html} diff --git a/vignettes/custom.qmd b/vignettes/custom.qmd index 96254aa1..a9f583a5 100644 --- a/vignettes/custom.qmd +++ b/vignettes/custom.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{Customization} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # Customization ```{=html} diff --git a/vignettes/faq.qmd b/vignettes/faq.qmd index f6bd46ca..84b98632 100644 --- a/vignettes/faq.qmd +++ b/vignettes/faq.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{FAQ} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # FAQ ```{=html} diff --git a/vignettes/format.qmd b/vignettes/format.qmd index a8721edf..0e1d5a59 100644 --- a/vignettes/format.qmd +++ b/vignettes/format.qmd @@ -1,4 +1,8 @@ --- +vignette: > + %\VignetteIndexEntry{Formatting} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} bibliography: bibliography.bib --- diff --git a/vignettes/group.qmd b/vignettes/group.qmd index b52ba90e..cd33979e 100644 --- a/vignettes/group.qmd +++ b/vignettes/group.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{Groups and labels} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # Groups and labels ```{=html} diff --git a/vignettes/introduction.qmd b/vignettes/introduction.qmd new file mode 100644 index 00000000..d25116a4 --- /dev/null +++ b/vignettes/introduction.qmd @@ -0,0 +1,128 @@ +--- +vignette: > + %\VignetteIndexEntry{An introduction to tinytable} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +

+ +
+ + + + + +

+ +## What? + +`tinytable` is a small but powerful `R` package to draw beautiful tables in a variety of formats: HTML, LaTeX, Word, PDF, PNG, Markdown, and Typst. The user interface is minimalist and easy to learn, while giving users access to powerful frameworks to create endlessly customizable tables. + + + +## Why? + +```{r, include=FALSE} +db <- tools::CRAN_package_db() +dep_ke <- tools::package_dependencies(c("kableExtra"), recursive=TRUE, db=db)[[1]] |> length() +dep_hux <- tools::package_dependencies(c("huxtable"), recursive=TRUE, db=db)[[1]] |> length() +dep_dt <- tools::package_dependencies(c("DT"), recursive=TRUE, db=db)[[1]] |> length() +dep_gt <- tools::package_dependencies(c("gt"), recursive=TRUE, db=db)[[1]] |> length() +``` + +There are already many excellent table-drawing packages in the `R` ecosystem. Why release a new one? As [the maintainer of `modelsummary`](https://modelsummary.com), I needed a table-drawing package which was: + +* *Simple*: Streamlined, consistent, and uncluttered user interface, with few functions to learn. +* *Flexible*: Expressive frameworks to customize tables in HTML and LaTeX formats.^[Other formats like Markdown and Typst are also available, but less flexible.] +* *Zero-dependency*: Avoid importing any other `R` package.^[Some extra packages can be imported to access specific functionality, such as integration with Quarto, inserting `ggplot2` objects as inline plots, and saving tables to PNG images or PDF documents.] +* *Concise*: Draw beautiful tables without typing a lot of code. +* *Safe*: User inputs are checked thoroughly, and informative errors are returned early. +* *Maintainable*: A small code base which does not rely on too many complex regular expressions. +* *Readable*: HTML and LaTeX code should be human-readable and editable. +* *Free*: This package will always be free. Tiny tables for a tiny price! + + +To achieve these goals, the design philosophy of `tinytable` rests on three pillars: + +(1) _Data is separate from style._ The code that this package creates keeps the content of a table separate from the style sheet that applies to its cells. This is in contrast to other `R` packages that modify the actual text in each cell to style it. Keeping data and style separate allows `tinytable` to create human-readable files which are easy to edit, debug, and extend. It also enables developers to keep a simpler code base, with minimal use of messy regular expressions. + +(2) _Flexibility._ Users' needs are extremely varied, and a table-drawing package must be flexible enough to accomodate different ideas. To achieve this, `tinytable` builds on battle-tested and versatile frameworks like `Bootstrap` for HTML and `tabularray` for LaTeX. + +(3) [_Lightweight is the right weight._](https://www.tinyverse.org/) Some of the most popular table-drawing packages in the `R` ecosystem are very heavy: A single `library()` call can sometimes load upwards of 65 `R` packages. In contrast, `tinytable` imports zero 3rd party `R` package by default. + + +## Installation + +`tinytable` is a relatively new package with rapid development. If you want to benefit from the latest features---showcased on the package website---you should install from R-Universe: + +``` r +install.packages("tinytable") +``` + +Alternatively, you can install it from CRAN: + +``` r +install.packages("tinytable") +``` + +Restart `R` completely for the installation to take effect. + + +## First steps + +The best feature of `tinytable` is its simplicity. To draw a table, simply call the `tt()` function with your data frame as the first argument: + +```r +library(tinytable) + +x <- mtcars[1:5, 1:5] + +tt(x) +``` + +

+ +
+ +More complex tables can be created by calling arguments and chaining functions together. In the next example, we add a caption, footnote, colors, styles, and spanning column headers: + +```r +cap <- "A simple \\texttt{tinytable} example." +not <- "Nullam odio est, ullamcorper scelerisque lectus a, eleifend luctus nisl. Etiam ullamcorper, nibh vel interdum auctor, odio nulla mollis tortor, vel fringilla ante quam quis est." + +tt(x, + caption = cap, + notes = not, + width = .5) |> + style_tt( + i = 1:3, + j = 1:2, + background = "teal", + color = "white", + bold = TRUE) |> + group_tt( + j = list("Halloumi" = 1:2, "Tofu" = 4:5)) +``` + +

+ +
+ + +## Tutorial + +The `tinytable` `r packageVersion("tinytable")` tutorial will take you much further. It is available in two formats: + +* [Tutorial (PDF)](https://vincentarelbundock.github.io/tinytable/vignettes/tinytable_tutorial.pdf) +* Tutorial (HTML): + - [Tiny tables](https://vincentarelbundock.github.io/tinytable/vignettes/tinytable.html) + - [Format](https://vincentarelbundock.github.io/tinytable/vignettes/format.html) + - [Style](https://vincentarelbundock.github.io/tinytable/vignettes/style.html) + - [Group labels](https://vincentarelbundock.github.io/tinytable/vignettes/group.html) + - [Plots and images](https://vincentarelbundock.github.io/tinytable/vignettes/plot.html) + - [Themes](https://vincentarelbundock.github.io/tinytable/vignettes/theme.html) + - [Customization](https://vincentarelbundock.github.io/tinytable/vignettes/custom.html) + - [FAQ](https://vincentarelbundock.github.io/tinytable/vignettes/faq.html) + - [Alternatives](https://vincentarelbundock.github.io/tinytable/vignettes/alternatives.html) + diff --git a/vignettes/options.qmd b/vignettes/options.qmd index 853706db..2f465995 100644 --- a/vignettes/options.qmd +++ b/vignettes/options.qmd @@ -1,4 +1,11 @@ -# Available Options +--- +vignette: > + %\VignetteIndexEntry{Global options} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +# Global options Options can be set with `options()` and change the default behavior of tinytable. You can either set them in a script (usually at the top) or via `.Rprofile`. Note that you want to [be cautious](https://rstats.wtf/r-startup.html) with putting things in `.Rprofile` since they might make results not reproducible (e.g. if you change `tinytable_format_digits` in `.Rprofile`, the table will be formatted differently). diff --git a/vignettes/plot.qmd b/vignettes/plot.qmd index eb289b92..ec281e78 100644 --- a/vignettes/plot.qmd +++ b/vignettes/plot.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{Plots and images} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # Plots and images ```{=html} diff --git a/vignettes/style.qmd b/vignettes/style.qmd index 470b23f1..cf3e4341 100644 --- a/vignettes/style.qmd +++ b/vignettes/style.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{Style} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # Style ```{=html} diff --git a/vignettes/theme.qmd b/vignettes/theme.qmd index 402ba799..9725712c 100644 --- a/vignettes/theme.qmd +++ b/vignettes/theme.qmd @@ -1,3 +1,10 @@ +--- +vignette: > + %\VignetteIndexEntry{Themes} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + # Themes ```{=html}