Crosslink documentation with book (#5678)

* crosslink docs with book

* Add helper function

* Use helper function

R/annotation.R

@@ -20,6 +20,8 @@
 #'   you must specify at least one of these.
 #' @inheritParams layer
 #' @inheritParams geom_point
+#' @seealso
+#' The `r link_book("custom annotations section", "annotations#sec-custom-annotations")`
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point()

R/coord-.R

@@ -44,6 +44,8 @@
 #'     system to manipulate the `layout` data frame which assigns
 #'     data to panels and scales.
 #'
+#' See also the `r link_book("new coords section", "extensions#sec-new-coords")`
+#'
 #' @rdname ggplot2-ggproto
 #' @format NULL
 #' @usage NULL

R/coord-map.R

@@ -45,6 +45,8 @@
 #'   setting of `"on"` (the default) means yes, and a setting of `"off"`
 #'   means no. For details, please see [`coord_cartesian()`].
 #' @export
+#' @seealso
+#' The `r link_book("polygon maps section", "maps#sec-polygonmaps")`
 #' @examples
 #' if (require("maps")) {
 #' nz <- map_data("nz")

R/coord-polar.R

@@ -12,6 +12,8 @@
 #'   setting of `"on"` (the default) means yes, and a setting of `"off"`
 #'   means no. For details, please see [`coord_cartesian()`].
 #' @export
+#' @seealso
+#' The `r link_book("polar coordinates section", "coord#polar-coordinates-with-coord_polar")`
 #' @examples
 #' # NOTE: Use these plots with caution - polar coordinates has
 #' # major perceptual problems.  The main point of these examples is

R/coord-transform.R

@@ -11,6 +11,8 @@
 #' @inheritParams coord_cartesian
 #' @param x,y Transformers for x and y axes or their names.
 #' @param limx,limy `r lifecycle::badge("deprecated")` use `xlim` and `ylim` instead.
+#' @seealso
+#' The `r link_book("coord transformations section", "coord#transformations-with-coord_trans")`
 #' @export
 #' @examples
 #' \donttest{

R/facet-.R

@@ -74,6 +74,8 @@ NULL
 #' parameter which is used to determine if scales are retrained after Stat
 #' transformations has been applied.
 #'
+#' See also the `r link_book("new facets section", "extensions#new-facets")`
+#'
 #' @rdname ggplot2-ggproto
 #' @format NULL
 #' @usage NULL

R/facet-grid-.R

@@ -70,6 +70,8 @@ NULL
 #'   draws the labels at the interior axes in the x- or y-direction
 #'   respectively.
 #' @export
+#' @seealso
+#' The `r link_book("facet grid section", "facet#facet-grid")`
 #' @examples
 #' p <- ggplot(mpg, aes(displ, cty)) + geom_point()
 #'

R/facet-wrap.R

@@ -35,6 +35,8 @@ NULL
 #'   `"all_x"` or `"all_y"`, only draws the labels at the interior axes in the
 #'   x- or y-direction respectively.
 #' @inheritParams facet_grid
+#' @seealso
+#' The `r link_book("facet wrap section", "facet#sec-facet-wrap")`
 #' @export
 #' @examples
 #' p <- ggplot(mpg, aes(displ, hwy)) + geom_point()

R/geom-.R

@@ -50,6 +50,8 @@ NULL
 #'     default values for aesthetics.
 #'   - `setup_data`: Converts width and height to xmin and xmax,
 #'     and ymin and ymax values. It can potentially set other values as well.
+#'
+#' See also the `r link_book("new geoms section", "extensions#sec-new-geoms")`
 #' @rdname ggplot2-ggproto
 #' @format NULL
 #' @usage NULL

R/geom-sf.R

@@ -59,7 +59,11 @@
 #'
 #'   You can also set this to one of "polygon", "line", and "point" to
 #'   override the default legend.
-#' @seealso [stat_sf_coordinates()]
+#'
+#' @seealso
+#' The `r link_book("simple feature maps section", "maps#sec-sf")`
+#'
+#' [stat_sf_coordinates()]
 #' @examples
 #' if (requireNamespace("sf", quietly = TRUE)) {
 #' nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

R/geom-text.R

@@ -63,6 +63,8 @@
 #'   (`"mm"`, default), points (`"pt"`), centimetres (`"cm"`), inches (`"in"`),
 #'   or picas (`"pc"`).
 #' @export
+#' @seealso
+#' The `r link_book("text labels section", "annotations#sec-text-labels")`
 #' @examples
 #' p <- ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars)))
 #'

R/ggproto.R

@@ -33,6 +33,8 @@
 #' @param _inherit ggproto object to inherit from. If `NULL`, don't
 #'   inherit from any object.
 #' @param ... A list of members in the ggproto object.
+#' @seealso
+#' The `r link_book("ggproto introduction section", "internals#sec-ggproto")`
 #' @export
 #' @examples
 #' Adder <- ggproto("Adder",

R/guide-colorbar.R

@@ -46,6 +46,8 @@ NULL
 #' @return A guide object
 #' @export
 #' @family guides
+#' @seealso
+#' The `r link_book("continuous legend section", "scales-colour#sec-guide-colourbar")`
 #' @examples
 #' df <- expand.grid(X1 = 1:10, X2 = 1:10)
 #' df$value <- df$X1 * df$X2

R/guide-colorsteps.R

@@ -19,6 +19,8 @@
 #' @export
 #'
 #' @family guides
+#' @seealso
+#' The `r link_book("binned legend section", "scales-colour#sec-guide-coloursteps")`
 #' @examples
 #' df <- expand.grid(X1 = 1:10, X2 = 1:10)
 #' df$value <- df$X1 * df$X2

R/guide-legend.R

@@ -32,6 +32,8 @@
 #' @param ... ignored.
 #' @export
 #' @family guides
+#' @seealso
+#' The `r link_book("legends section", "scales-colour#sec-guide-legend")`
 #' @examples
 #' \donttest{
 #' df <- expand.grid(X1 = 1:10, X2 = 1:10)

R/labels.R

@@ -47,6 +47,9 @@ update_labels <- function(p, labels) {
 #'        See [get_alt_text] for examples.
 #' @param ... A list of new name-value pairs. The name should be an aesthetic.
 #' @export
+#'
+#' @seealso
+#' The `r link_book("plot and axis titles section", "annotations#sec-titles")`
 #' @examples
 #' p <- ggplot(mtcars, aes(mpg, wt, colour = cyl)) + geom_point()
 #' p + labs(colour = "Cylinders")

R/layer.R

@@ -72,6 +72,8 @@
 #' @param layer_class The type of layer object to be constructed. This is
 #'   intended for ggplot2 internal use only.
 #' @keywords internal
+#' @seealso
+#' The `r link_book(c("plot building chapter", "geoms chapter"), c("layers", "individual-geoms"))`
 #' @family layer documentation
 #' @examples
 #' # geom calls are just a short cut for layer

R/plot-build.R

@@ -15,9 +15,12 @@
 #'   plot). In `layer_scales()`, the row of a facet to return scales for.
 #' @param j An integer. In `layer_scales()`, the column of a facet to return
 #'   scales for.
-#' @seealso [print.ggplot()] and [benchplot()] for
-#'  functions that contain the complete set of steps for generating
-#'  a ggplot2 plot.
+#' @seealso
+#' [print.ggplot()] and [benchplot()] for
+#' functions that contain the complete set of steps for generating
+#' a ggplot2 plot.
+#'
+#' The `r link_book("build step section", "internals#sec-ggplotbuild")`
 #' @keywords internal
 #' @export
 ggplot_build <- function(plot) {
@@ -156,9 +159,12 @@ layer_grob <- function(plot = last_plot(), i = 1L) {
 #' to (e.g.) make the legend box 2 cm wide, or combine multiple plots into
 #' a single display, preserving aspect ratios across the plots.
 #'
-#' @seealso [print.ggplot()] and [benchplot()] for
-#'  for functions that contain the complete set of steps for generating
-#'  a ggplot2 plot.
+#' @seealso
+#' [print.ggplot()] and [benchplot()] for
+#' for functions that contain the complete set of steps for generating
+#' a ggplot2 plot.
+#'
+#' The `r link_book("gtable step section", "internals#sec-ggplotgtable")`
 #' @return a [gtable()] object
 #' @keywords internal
 #' @param data plot data generated by [ggplot_build()]

R/plot.R

@@ -44,6 +44,8 @@
 #' @param environment `r lifecycle::badge("deprecated")` Used prior to tidy
 #'   evaluation.
 #' @export
+#' @seealso
+#' The `r link_book("first steps chapter", "getting-started")`
 #' @examples
 #' # Create a data frame with some sample data, then create a data frame
 #' # containing the mean value for each group in the sample data.

R/position-.R

@@ -37,6 +37,8 @@
 #'   - `required_aes`: a character vector giving the aesthetics
 #'      that must be present for this position adjustment to work.
 #'
+#' See also the `r link_book("new positions section", "extensions#new-positions")`
+#'
 #' @rdname ggplot2-ggproto
 #' @format NULL
 #' @usage NULL

R/save.R

@@ -49,6 +49,9 @@
 #'   a prompt will appear asking to create a new directory when necessary.
 #' @param ... Other arguments passed on to the graphics device function,
 #'   as specified by `device`.
+#'
+#' @seealso
+#' The `r link_book("saving section", "themes#sec-saving")`
 #' @export
 #' @examples
 #' \dontrun{

R/scale-.R

@@ -94,6 +94,10 @@
 #' `left` or `right` for y axes, `top` or `bottom` for x axes.
 #' @param call The `call` used to construct the scale for reporting messages.
 #' @param super The super class to use for the constructed scale
+#'
+#' @seealso
+#' The `r link_book("new scales section", "extensions#sec-new-scales")`
+#'
 #' @keywords internal
 continuous_scale <- function(aesthetics, scale_name = deprecated(), palette, name = waiver(),
                              breaks = waiver(), minor_breaks = waiver(), n.breaks = NULL,
@@ -191,6 +195,8 @@ continuous_scale <- function(aesthetics, scale_name = deprecated(), palette, nam
 #' @param na.value If `na.translate = TRUE`, what aesthetic value should the
 #'   missing values be displayed as? Does not apply to position scales
 #'   where `NA` is always placed at the far right.
+#' @seealso
+#' The `r link_book("new scales section", "extensions#sec-new-scales")`
 #' @keywords internal
 discrete_scale <- function(aesthetics, scale_name = deprecated(), palette, name = waiver(),
                            breaks = waiver(), labels = waiver(), limits = NULL, expand = waiver(),
@@ -272,6 +278,8 @@ discrete_scale <- function(aesthetics, scale_name = deprecated(), palette, name
 #'   left), whereas they are part of the upper bin when intervals are closed on
 #'   the left (open on the right).
 #' @param show.limits should the limits of the scale appear as ticks
+#' @seealso
+#' The `r link_book("new scales section", "extensions#sec-new-scales")`
 #' @keywords internal
 binned_scale <- function(aesthetics, scale_name = deprecated(), palette, name = waiver(),
                          breaks = waiver(), labels = waiver(), limits = NULL,

R/scale-alpha.R

@@ -16,6 +16,8 @@
 #' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #'
 #' Other alpha scales: [scale_alpha_manual()], [scale_alpha_identity()].
+#'
+#' The `r link_book("alpha scales section", "scales-colour#sec-scales-alpha")`
 #' @export
 #' @examples
 #' p <- ggplot(mpg, aes(displ, hwy)) +

R/scale-binned.R

@@ -10,6 +10,8 @@
 #' @family position scales
 #' @seealso
 #' The [position documentation][aes_position].
+#'
+#' The `r link_book("binned position scales section", "scales-position#sec-binned-position")`
 #' @name scale_binned
 #' @aliases NULL
 #'

R/scale-brewer.R

@@ -40,6 +40,8 @@
 #' @family colour scales
 #' @seealso
 #' The documentation on [colour aesthetics][aes_colour_fill_alpha].
+#'
+#' The `r link_book("brewer scales section", "scales-colour#brewer-scales")`
 #' @rdname scale_brewer
 #' @export
 #' @examples

R/scale-colour.R

@@ -39,6 +39,8 @@
 #'   The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @family colour scales
 #' @rdname scale_colour_continuous
+#' @seealso
+#' The `r link_book("continuous colour scales section", "scales-colour#sec-colour-continuous")`
 #' @section Color Blindness:
 #' Many color palettes derived from RGB combinations (like the "rainbow" color
 #' palette) are not suitable to support all viewers, especially those with

R/scale-continuous.R

@@ -13,6 +13,8 @@
 #' @seealso
 #' The [position documentation][aes_position].
 #'
+#' The `r link_book("numeric position scales section", "scales-position#sec-numeric-position-scales")`
+#'
 #' @param ... Other arguments passed on to `scale_(x|y)_continuous()`
 #' @examples
 #' p1 <- ggplot(mpg, aes(displ, hwy)) +

R/scale-date.R

@@ -35,7 +35,9 @@
 #'   (`NULL`) uses the timezone encoded in the data.
 #' @family position scales
 #' @seealso
-#' [sec_axis()] for how to specify secondary axes
+#' [sec_axis()] for how to specify secondary axes.
+#'
+#' The `r link_book("date-time position scales section", "scales-position#sec-date-scales")`
 #'
 #' The [position documentation][aes_position].
 #' @examples

R/scale-discrete-.R

@@ -16,6 +16,8 @@
 #' @family position scales
 #' @seealso
 #' The [position documentation][aes_position].
+#'
+#' The `r link_book("discrete position scales section", "scales-position#sec-discrete-position")`
 #' @export
 #' @examples
 #' ggplot(diamonds, aes(cut)) + geom_bar()

R/scale-grey.R

@@ -9,6 +9,8 @@
 #' @family colour scales
 #' @seealso
 #' The documentation on [colour aesthetics][aes_colour_fill_alpha].
+#'
+#' The `r link_book("hue and grey scales section", "scales-colour#hue-and-grey-scales")`
 #' @rdname scale_grey
 #' @export
 #' @examples

R/scale-hue.R

@@ -16,6 +16,8 @@
 #' @family colour scales
 #' @seealso
 #' The documentation on [colour aesthetics][aes_colour_fill_alpha].
+#'
+#' The `r link_book("hue and grey scales section", "scales-colour#hue-and-grey-scales")`
 #' @examples
 #' \donttest{
 #' set.seed(596)
@@ -97,6 +99,8 @@ scale_fill_hue <- function(name = waiver(), ..., h = c(0, 360) + 15, c = 100,
 #'   * A function that returns a discrete colour/fill scale (e.g., [scale_fill_hue()],
 #'   [scale_fill_brewer()], etc).
 #' @export
+#' @seealso
+#' The `r link_book("discrete colour scales section", "scales-colour#sec-colour-discrete")`
 #' @examples
 #' # Template function for creating densities grouped by a variable
 #' cty_by_var <- function(var) {

R/scale-identity.R

@@ -23,6 +23,8 @@
 #' @param guide Guide to use for this scale. Defaults to `"none"`.
 #' @inheritParams continuous_scale
 #' @family colour scales
+#' @seealso
+#' The `r link_book("identity scales section", "scales-other#sec-scale-identity")`
 #' @examples
 #' ggplot(luv_colours, aes(u, v)) +
 #'   geom_point(aes(colour = col), size = 3) +

R/scale-linetype.R

@@ -13,6 +13,8 @@
 #' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
 #'
 #' Other linetype scales: [scale_linetype_manual()], [scale_linetype_identity()].
+#'
+#' The `r link_book("line type section", "scales-other#sec-scale-linetype")`
 #' @export
 #' @examples
 #' base <- ggplot(economics_long, aes(date, value01))

R/scale-linewidth.R

@@ -10,6 +10,8 @@
 #' @inheritParams binned_scale
 #' @seealso
 #' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
+#'
+#' The `r link_book("line width section", "scales-other#sec-scale-linewidth")`
 #' @param range a numeric vector of length 2 that specifies the minimum and
 #'   maximum size of the plotting symbol after transformation.
 #' @examples

R/scale-manual.R

@@ -35,6 +35,8 @@
 #'
 #' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #'
+#' The `r link_book(c("manual scales", "manual colour scales sections"), c("scales-other#sec-scale-manual", "scales-colour#sec-manual-colour"))`
+#'
 #' @section Color Blindness:
 #' Many color palettes derived from RGB combinations (like the "rainbow" color
 #' palette) are not suitable to support all viewers, especially those with

R/scale-shape.R

@@ -16,6 +16,8 @@
 #' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
 #'
 #' Other shape scales: [scale_shape_manual()], [scale_shape_identity()].
+#'
+#' The `r link_book("shape section", "scales-other#sec-scale-shape")`
 #' @export
 #' @examples
 #' set.seed(596)