Merge branch 'master' into refactor-heading-component

* master:
  Use webshot to generate images of HTML tables (#257)
  Rewritten vignette for adding summary rows (#273)
  Move roxygen documentation to Markdown (#253)
  Store empty-string value in `sep` vector (#274)
  Bugfixes and improvements to `summary_rows()` (#175)
  Modify _travis.yml (#263)
  Make several refactoring improvements to some `format_*()` functions (#244)
  Include option to hide all column labels (#237)

.travis.yml

@@ -2,24 +2,27 @@
 
 language: R
 sudo: false
-cache: packages
+cache:
+  packages: true
 warnings_are_errors: false
 
+r:
+  - oldrel
+  - release
+  - devel
+
 notifications:
   email:
     on_success: change
     on_failure: change
 
 jobs:
   include:
-    - stage: "R CMD check"
-      r: oldrel
-    - r: release
-    - r: devel
-
     - stage: deploy
       name: covr
       r: release
+      cache:
+        packages: false
       r_binary_packages:
         - covr
       script:
@@ -28,13 +31,19 @@ jobs:
     - stage: deploy
       name: pkgdown
       r: release
-      if: branch IN (master)
+      cache:
+        packages: false
+      if: |
+        branch IN (master, travis) AND \
+        type = push AND \
+        repo = rstudio/gt
       r_binary_packages:
         - pkgdown
+        - remotes
       script:
-        - Rscript -e "devtools::install()"
+        - Rscript -e "remotes::install_local()"
         - Rscript -e "pkgdown::build_site()"
-        - Rscript -e "remove.packages(devtools::as.package('.')$package)"
+        - Rscript -e "remove.packages('gt')"
       deploy:
         provider: pages
         local-dir: docs

DESCRIPTION

@@ -50,3 +50,4 @@ Suggests:
     shiny,
     xml2
 VignetteBuilder: knitr
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -8,6 +8,7 @@ export(as_raw_html)
 export(as_rtf)
 export(cells_column_labels)
 export(cells_data)
+export(cells_grand_summary)
 export(cells_group)
 export(cells_stub)
 export(cells_styles)
@@ -41,6 +42,7 @@ export(fmt_percent)
 export(fmt_scientific)
 export(fmt_time)
 export(ggplot_image)
+export(grand_summary_rows)
 export(gt)
 export(gt_latex_dependencies)
 export(gt_output)

R/as_latex.R

@@ -1,13 +1,12 @@
 #' Output a \pkg{gt} object as LaTeX
 #'
-#' Get the LaTeX content from a \code{gt_tbl} object as a \code{knit_asis}
-#' object. This object contains the LaTeX code and attributes that serve as
-#' LaTeX dependencies (i.e., the LaTeX packages required for the table). Using
-#' \code{as.character()} on the created object will result in a single-element
-#' vector containing the LaTeX code.
+#' Get the LaTeX content from a `gt_tbl` object as a `knit_asis` object. This
+#' object contains the LaTeX code and attributes that serve as LaTeX
+#' dependencies (i.e., the LaTeX packages required for the table). Using
+#' `as.character()` on the created object will result in a single-element vector
+#' containing the LaTeX code.
 #'
-#' @param data a table object that is created using the \code{\link{gt}()}
-#'   function.
+#' @param data A table object that is created using the [gt()] function.
 #' @import rlang
 #' @importFrom dplyr mutate group_by summarize ungroup rename arrange
 #' @importFrom stats setNames

R/as_raw_html.R

@@ -1,14 +1,13 @@
 #' Get the HTML content of a \pkg{gt} table
 #'
-#' Get the HTML content from a \code{gt_tbl} object as a single-element
-#' character vector. By default, the generated HTML will have inlined styles,
-#' where CSS styles (that were previously contained in CSS rule sets external to
-#' the \code{<table> element}) are included as \code{style} attributes in the
-#' HTML table's tags. This option is preferable when using the output HTML table
-#' in an emailing context.
-#' @param data a table object that is created using the \code{\link{gt}()}
-#'   function.
-#' @param inline_css an option to supply styles to table elements as inlined CSS
+#' Get the HTML content from a `gt_tbl` object as a single-element character
+#' vector. By default, the generated HTML will have inlined styles, where CSS
+#' styles (that were previously contained in CSS rule sets external to the
+#' `<table> element`) are included as `style` attributes in the HTML table's
+#' tags. This option is preferable when using the output HTML table in an
+#' emailing context.
+#' @param data A table object that is created using the [gt()] function.
+#' @param inline_css An option to supply styles to table elements as inlined CSS
 #'   styles.
 #' @examples
 #' # Use `gtcars` to create a gt table;

R/as_rtf.R

@@ -1,10 +1,10 @@
 #' Output a \pkg{gt} object as RTF
 #'
-#' Get the RTF content from a \code{gt_tbl} object as as a single-element
-#' character vector. This object can be used with \code{writeLines()} to
-#' generate a valid .rtf file that can be opened by RTF readers.
+#' Get the RTF content from a `gt_tbl` object as as a single-element character
+#' vector. This object can be used with `writeLines()` to generate a valid .rtf
+#' file that can be opened by RTF readers.
 #'
-#' @param data a table object that is created using the \code{gt()} function.
+#' @param data a table object that is created using the `gt()` function.
 #' @examples
 #' # Use `gtcars` to create a gt table;
 #' # add a header and then export as
@@ -179,7 +179,9 @@ as_rtf <- function(data) {
 
   # Perform any necessary column merge operations
   col_merge_output <-
-    perform_col_merge(col_merge, data_df, output_df, boxh_df, columns_df)
+    perform_col_merge(
+      col_merge, data_df, output_df, boxh_df, columns_df, context
+    )
 
   # Rewrite `output_df`, `boxh_df`, and `columns_df` as a result of merging
   output_df <- col_merge_output$output_df
@@ -188,7 +190,7 @@ as_rtf <- function(data) {
 
   # Create the `list_of_summaries` list of lists
   list_of_summaries <-
-    create_summary_dfs(summary_list, data_df, stub_df, output_df)
+    create_summary_dfs(summary_list, data_df, stub_df, output_df, context)
 
   # Determine if there is a populated stub
   stub_available <- is_stub_available(stub_df)

R/build_data.R

@@ -156,7 +156,9 @@ build_data <- function(data, context) {
 
   # Perform any necessary column merge operations
   col_merge_output <-
-    perform_col_merge(col_merge, data_df, output_df, boxh_df, columns_df)
+    perform_col_merge(
+      col_merge, data_df, output_df, boxh_df, columns_df, context
+    )
 
   # Rewrite `output_df`, `boxh_df`, and `columns_df` as a result of merging
   output_df <- col_merge_output$output_df
@@ -165,7 +167,7 @@ build_data <- function(data, context) {
 
   # Create the `list_of_summaries` list of lists
   list_of_summaries <-
-    create_summary_dfs(summary_list, data_df, stub_df, output_df)
+    create_summary_dfs(summary_list, data_df, stub_df, output_df, context)
 
   # Determine if there is a populated stub
   stub_available <- is_stub_available(stub_df)

R/data_color.R

@@ -1,71 +1,71 @@
 #' Set data cell colors using a palette or a color function
 #'
 #' It's possible to add color to data cells according to their values. The
-#' \code{data_color()} function colors all rows of any \code{columns} supplied.
-#' There are two ways to define how cells are colored: (1) through the use of a
-#' supplied color palette, and (2) through use of a color mapping function
-#' available from the \code{scales} package. The first method colorizes cell
-#' data according to whether values are character or numeric. The second method
-#' provides more control over how cells are colored since we provide an explicit
-#' color function and thus other requirements such as bin counts, cut points, or
-#' a numeric domain. Finally, we can choose whether to apply the cell-specific
+#' `data_color()` function colors all rows of any `columns` supplied. There are
+#' two ways to define how cells are colored: (1) through the use of a supplied
+#' color palette, and (2) through use of a color mapping function available from
+#' the `scales` package. The first method colorizes cell data according to
+#' whether values are character or numeric. The second method provides more
+#' control over how cells are colored since we provide an explicit color
+#' function and thus other requirements such as bin counts, cut points, or a
+#' numeric domain. Finally, we can choose whether to apply the cell-specific
 #' colors to either the cell background or the cell text.
 #'
-#' The \code{col_*()} functions from the scales package can be used in the
-#' \code{colors} argument. These functions map data values (\code{numeric} or
-#' \code{factor}/\code{character}) to colors according to the provided palette.
+#' The `col_*()` functions from the scales package can be used in the `colors`
+#' argument. These functions map data values (`numeric` or `factor`/`character`)
+#' to colors according to the provided palette.
 #'
 #' \itemize{
-#' \item \code{\link[scales]{col_numeric}()}: provides a simple linear mapping
+#' \item [scales::col_numeric()]: provides a simple linear mapping
 #' from continuous numeric data to an interpolated palette.
-#' \item \code{\link[scales]{col_bin}()}: provides a mapping of continuous
+#' \item [scales::col_bin()]: provides a mapping of continuous
 #' numeric data to value-based bins. This internally uses the
-#' \code{\link[base]{cut}()} function.
-#' \item \code{\link[scales]{col_quantile}()}: provides a mapping of continuous
+#' [base::cut()] function.
+#' \item [scales::col_quantile()]: provides a mapping of continuous
 #' numeric data to quantiles. This internally uses the
-#' \code{\link[stats]{quantile}()} function.
-#' \item \code{\link[scales]{col_factor}()}: provides a mapping of factors to
+#' [stats::quantile()] function.
+#' \item [scales::col_factor()]: provides a mapping of factors to
 #' colors. If the palette is discrete and has a different number of colors than
 #' the number of factors, interpolation is used.
 #' }
 #'
 #' By default, \pkg{gt} will choose the ideal text color (for maximal contrast)
 #' when colorizing the background of data cells. This option can be disabled by
-#' setting \code{autocolor_text} to \code{FALSE}.
+#' setting `autocolor_text` to `FALSE`.
 #'
 #' Choosing the right color palette can often be difficult because it's both
 #' hard to discover suitable palettes and then obtain the vector of colors. To
 #' make this process easier we can elect to use the \pkg{paletteer} package,
 #' which makes a wide range of palettes from various R packages readily
-#' available. The \code{\link{info_paletteer}()} information table allows us to
-#' easily inspect all of the discrete color palettes available in
-#' \pkg{paletteer}. We only then need to specify the \code{package} and
-#' \code{palette} when calling the \code{paletteer::paletteer_d()} function,
-#' and, we get the palette as a vector of hexadecimal colors.
+#' available. The [info_paletteer()] information table allows us to easily
+#' inspect all of the discrete color palettes available in \pkg{paletteer}. We
+#' only then need to specify the `package` and `palette` when calling the
+#' `paletteer::paletteer_d()` function, and, we get the palette as a vector of
+#' hexadecimal colors.
 #'
 #' @inheritParams fmt_number
-#' @param columns the columns wherein changes to cell data colors should occur.
-#' @param colors either a color mapping function from the \code{scales} package
+#' @param columns The columns wherein changes to cell data colors should occur.
+#' @param colors Either a color mapping function from the `scales` package
 #'   or a vector of colors to use for each distinct value or level in each of
-#'   the provided \code{columns}. The color mapping functions are:
-#'   \code{scales::col_quantile()}, \code{scales::col_bin()},
-#'   \code{scales::col_numeric()}, and \code{scales::col_factor()}. If providing
+#'   the provided `columns`. The color mapping functions are:
+#'   `scales::col_quantile()`, `scales::col_bin()`,
+#'   `scales::col_numeric()`, and `scales::col_factor()`. If providing
 #'   a vector of colors as a palette, each color value provided must either be a
-#'   color name (in the set of colors provided by \code{grDevices::colors()}) or
+#'   color name (in the set of colors provided by `grDevices::colors()`) or
 #'   a hexadecimal string in the form of "#RRGGBB" or "#RRGGBBAA".
-#' @param alpha an optional, fixed alpha transparency value that will be applied
-#'   to all of the \code{colors} provided if they are provided as a vector of
-#'   colors. If using a colorizing helper function for \code{colors} then this
+#' @param alpha An optional, fixed alpha transparency value that will be applied
+#'   to all of the `colors` provided if they are provided as a vector of
+#'   colors. If using a colorizing helper function for `colors` then this
 #'   option is ignored (each of the colorizing helper functions has its own
-#'   \code{alpha} argument).
-#' @param apply_to which style element should the colors be applied to? Options
-#'   include the cell background (the default, given as \code{bkgd}) or the cell
-#'   text (\code{text}).
-#' @param autocolor_text an option to let \pkg{gt} modify the coloring of text
+#'   `alpha` argument).
+#' @param apply_to Which style element should the colors be applied to? Options
+#'   include the cell background (the default, given as `bkgd`) or the cell
+#'   text (`text`).
+#' @param autocolor_text An option to let \pkg{gt} modify the coloring of text
 #'   within cells undergoing background coloring. This will in some cases yield
 #'   more optimal text-to-background color contrast. By default, this is set to
-#'   \code{TRUE}.
-#' @return an object of class \code{gt_tbl}.
+#'   `TRUE`.
+#' @return An object of class `gt_tbl`.
 #' @examples
 #' # library(paletteer)
 #'
@@ -235,7 +235,9 @@ data_color <- function(data,
   data
 }
 
-# Apply color scale styles to the gt table data
+#' Apply color scale styles to the gt table data
+#'
+#' @noRd
 scale_apply_styles <- function(data,
                                column,
                                styles,
@@ -278,17 +280,17 @@ scale_apply_styles <- function(data,
 #' apply greater darkening or lightening for those colors in the midrange
 #' compared to any very dark or very light colors in the input palette.
 #'
-#' This function can be useful when combined with the \code{\link{data_color}()}
-#' function's \code{palette} argument, which can use a vector of colors or any
-#' of the \code{col_*} functions from the \pkg{scales} package (all of which
-#' have a \code{palette} argument).
+#' This function can be useful when combined with the [data_color()] function's
+#' `palette` argument, which can use a vector of colors or any of the `col_*`
+#' functions from the \pkg{scales} package (all of which have a `palette`
+#' argument).
 #'
-#' @param colors a vector of colors that will undergo an adjustment in
+#' @param colors A vector of colors that will undergo an adjustment in
 #'   luminance. Each color value provided must either be a color name (in the
-#'   set of colors provided by \code{grDevices::colors()}) or a hexadecimal
-#'   string in the form of "#RRGGBB" or "#RRGGBBAA".
-#' @param steps a positive or negative factor by which the luminance will be
-#'   adjusted. Must be a number between \code{-2.0} and \code{2.0}.
+#'   set of colors provided by `grDevices::colors()`) or a hexadecimal string in
+#'   the form of "#RRGGBB" or "#RRGGBBAA".
+#' @param steps A positive or negative factor by which the luminance will be
+#'   adjusted. Must be a number between `-2.0` and `2.0`.
 #' @examples
 #' # Get a palette of 8 pastel colors from
 #' # the RColorBrewer package
@@ -378,7 +380,9 @@ adjust_luminance <- function(colors,
   hcl_colors
 }
 
-# Extract a vector of alpha values for a vector of colors
+#' Extract a vector of alpha values for a vector of colors
+#'
+#' @noRd
 get_alpha_vec <- function(colors) {
 
   alpha <- c()
@@ -397,8 +401,8 @@ get_alpha_vec <- function(colors) {
   alpha
 }
 
-# Function for determining the best `light` and `dark` colors to appear above a
-# background color
+#' Determining the best `light` and `dark` colors for contrast
+#'
 #' @importFrom grDevices col2rgb
 #' @noRd
 ideal_fgnd_color <- function(bgnd_colors,