Skip to content

Commit

Permalink
Merge pull request #1658 from olivroy/family
Browse files Browse the repository at this point in the history
Reduce doc duplication of location helpers
  • Loading branch information
rich-iannone authored May 12, 2024
2 parents 39b58b2 + 398b88c commit 18b06ab
Showing 44 changed files with 254 additions and 1,689 deletions.
1 change: 1 addition & 0 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -136,6 +136,7 @@ Collate:
'tab_remove.R'
'tab_style_body.R'
'text_transform.R'
'topics.R'
'utils.R'
'utils_color_contrast.R'
'utils_environments.R'
572 changes: 26 additions & 546 deletions R/helpers.R

Large diffs are not rendered by default.

22 changes: 11 additions & 11 deletions R/tab_create_modify.R
Original file line number Diff line number Diff line change
@@ -2063,8 +2063,8 @@ tab_stub_indent <- function(
#'
#' Each call of `tab_footnote()` will either add a different footnote to the
#' footer or reuse existing footnote text therein. One or more cells outside of
#' the footer are targeted using the `cells_*()` helper functions (e.g.,
#' [cells_body()], [cells_column_labels()], etc.). You can choose to *not*
#' the footer are targeted using the [`cells_*()`][location-helper] helper functions
#' (e.g., [cells_body()], [cells_column_labels()], etc.). You can choose to *not*
#' attach a footnote mark by simply not specifying anything in the `locations`
#' argument.
#'
@@ -2085,7 +2085,7 @@ tab_stub_indent <- function(
#'
#' @param locations *Locations to target*
#'
#' `<locations expressions>` // *default:* `NULL` (`optional`)
#' [`<locations expressions>`][location-helper] // *default:* `NULL` (`optional`)
#'
#' The cell or set of cells to be associated with the footnote. Supplying any
#' of the `cells_*()` helper functions is a useful way to target the location
@@ -2873,12 +2873,12 @@ tab_caption <- function(
#'
#' @description
#'
#' With the `tab_style()` function we can target specific cells and apply styles
#' to them. This is best done in conjunction with the helper functions
#' [cell_text()], [cell_fill()], and [cell_borders()]. At present this function
#' is focused on the application of styles for HTML output only (as such, other
#' output formats will ignore all `tab_style()` calls). Using the aforementioned
#' helper functions, here are some of the styles we can apply:
#' With the `tab_style()` function we can [target specific cells][location-helper]
#' and apply styles to them. This is best done in conjunction with the helper
#' functions [cell_text()], [cell_fill()], and [cell_borders()]. Currently, this
#' function is focused on the application of styles for HTML output only
#' (as such, other output formats will ignore all `tab_style()` calls).
#' Using the aforementioned helper functions, here are some of the styles we can apply:
#'
#' - the background color of the cell ([cell_fill()]: `color`)
#' - the cell's text color, font, and size ([cell_text()]: `color`, `font`,
@@ -2906,7 +2906,7 @@ tab_caption <- function(
#'
#' @param locations *Locations to target*
#'
#' `<locations expressions>` // **required**
#' [`<locations expressions>`][location-helper] // **required**
#'
#' The cell or set of cells to be associated with the style. Supplying any of
#' the `cells_*()` helper functions is a useful way to target the location
@@ -3232,7 +3232,7 @@ tab_caption <- function(
#'
#' @seealso [cell_text()], [cell_fill()], and [cell_borders()] as helpers for
#' defining custom styles and [cells_body()] as one of many useful helper
#' functions for targeting the locations to be styled.
#' functions for targeting the [locations][location-helper] to be styled.
#'
#' @export
tab_style <- function(
36 changes: 6 additions & 30 deletions R/text_transform.R
Original file line number Diff line number Diff line change
@@ -52,15 +52,7 @@
#'
#' The replacement text for any matched text fragments.
#'
#' @param locations *Locations to target*
#'
#' `<locations expressions>` // *default:* `cells_body()`
#'
#' The cell or set of cells to be associated with the text transformation.
#' Only the [cells_body()], [cells_stub()], [cells_row_groups()],
#' [cells_column_labels()], and [cells_column_spanners()] helper functions can
#' be used here. We can enclose several of these calls within a `list()` if we
#' wish to make the transformation happen at different locations.
#' @inheritParams text_transform
#'
#' @return An object of class `gt_tbl`.
#'
@@ -162,15 +154,7 @@ text_replace <- function(
#' The replacement text to use when cell values aren't matched by any of the
#' LHS inputs. If `NULL`, the default, no replacement text will be used.
#'
#' @param .locations *Locations to target*
#'
#' `<locations expressions>` // *default:* `cells_body()`
#'
#' The cell or set of cells to be associated with the text transformation.
#' Only the [cells_body()], [cells_stub()], [cells_row_groups()],
#' [cells_column_labels()], and [cells_column_spanners()] helper functions can
#' be used here. We can enclose several of these calls within a `list()` if we
#' wish to make the transformation happen at different locations.
#' @inheritParams text_transform
#'
#' @return An object of class `gt_tbl`.
#'
@@ -324,15 +308,7 @@ text_case_when <- function(
#' substrings of `old_text`. In this way, the replacements will act on those
#' matched substrings.
#'
#' @param .locations *Locations to target*
#'
#' `<locations expressions>` // *default:* `cells_body()`
#'
#' The cell or set of cells to be associated with the text transformation.
#' Only the [cells_body()], [cells_stub()], [cells_row_groups()],
#' [cells_column_labels()], and [cells_column_spanners()] helper functions can
#' be used here. We can enclose several of these calls within a `list()` if we
#' wish to make the transformation happen at different locations.
#' @inheritParams text_transform
#'
#' @return An object of class `gt_tbl`.
#'
@@ -518,11 +494,11 @@ text_case_match <- function(
#'
#' @param locations *Locations to target*
#'
#' `<locations expressions>` // *default:* `cells_body()`
#' [`<locations expressions>`][location-helper] // *default:* `cells_body()`
#'
#' The cell or set of cells to be associated with the text transformation.
#' Only the [cells_body()], [cells_stub()], [cells_row_groups()],
#' [cells_column_labels()], and [cells_column_spanners()] helper functions can
#' Only the [cells_column_spanners()], [cells_column_labels()],
#' [cells_row_groups()], [cells_stub()], and [cells_body()] helper functions can
#' be used here. We can enclose several of these calls within a `list()` if we
#' wish to make the transformation happen at different locations.
#'
58 changes: 58 additions & 0 deletions R/topics.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
#' Helper to target cells at `locations`
#'
#' @name location-helper
#' @description
#' This listing with locations corresponding roughly from top to
#' bottom of a table:
#'
#' - [cells_title()]: targets the table title or the table subtitle depending on
#' the value given to the `groups` argument (`"title"` or `"subtitle"`).
#' - [cells_stubhead()]: targets the stubhead location, a cell of which is only
#' available when there is a stub; a label in that location can be created by
#' using the [tab_stubhead()] function.
#' - [cells_column_spanners()]*: targets the spanner column labels with the
#' `spanners` argument; spanner column labels appear above the column labels.
#' - [cells_column_labels()]*: targets the column labels with its `columns`
#' argument.
#' - [cells_row_groups()]*: targets the row group labels in any available row
#' groups using the `groups` argument.
#' - [cells_stub()]*: targets row labels in the table stub using the `rows`
#' argument.
#' - [cells_body()]*: targets data cells in the table body using intersections of
#' `columns` and `rows`.
#' - [cells_summary()]: targets summary cells in the table body using the
#' `groups` argument and intersections of `columns` and `rows`.
#' - [cells_grand_summary()]: targets cells of the table's grand summary using
#' intersections of `columns` and `rows`
#' - [cells_stub_summary()]: targets summary row labels in the table stub using
#' the `groups` and `rows` arguments.
#' - [cells_stub_grand_summary()]: targets grand summary row labels in the table
#' stub using the `rows` argument.
#' - [cells_footnotes()]: targets all footnotes in the table footer (cannot be
#' used with [tab_footnote()]).
#' - [cells_source_notes()]: targets all source notes in the table footer
#' (cannot be used with [tab_footnote()]).
#'
#' `*` are the only functions usable by the `text_*()` functions.
#'
#' # Note
#'
#' When using any of the location helper functions with an appropriate function
#' that has a `locations` argument (e.g., [tab_style()]), multiple locations
#' can be targeted by enclosing several `cells_*()` helper functions in a
#' `list()` (e.g., `list(cells_body(), cells_grand_summary())`).
#'
#' @family location helper functions
#'
#' @seealso
#' Functions with `locations` argument:
#'
#' * [tab_footnote()]
#' * [tab_style()]
#' * [text_transform()]
#' * [text_replace()]
#' * [text_case_when()]
#' * [text_case_match()]
#'
#' These functions contain more example of usage.
NULL
13 changes: 0 additions & 13 deletions man/adjust_luminance.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 0 additions & 13 deletions man/cell_borders.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 0 additions & 13 deletions man/cell_fill.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 0 additions & 13 deletions man/cell_text.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

68 changes: 4 additions & 64 deletions man/cells_body.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 18b06ab

Please sign in to comment.