Doc tweaks for themes

Author: hadley

R/geom-.r

@@ -154,6 +154,8 @@ Geom <- ggproto("Geom",
 #' that grid uses internally for \code{lwd} and \code{fontsize}.
 #'
 #' @name graphical-units
+#' @keywords internal
+#' @aliases NULL
 NULL
 
 #' @export

R/margins.R

@@ -1,17 +1,8 @@
-#' Define margins.
-#'
-#' This is a convenient function that creates a grid unit object of the
-#' correct length to use for setting margins.
-#'
-#' @export
 #' @param t,r,b,l Dimensions of each margin. (To remember order, think trouble).
 #' @param unit Default units of dimensions. Defaults to "pt" so it
 #'   can be most easily scaled with the text.
+#' @rdname element
 #' @export
-#' @examples
-#' margin(4)
-#' margin(4, 2)
-#' margin(4, 3, 2, 1)
 margin <- function(t = 0, r = 0, b = 0, l = 0, unit = "pt") {
   structure(unit(c(t, r, b, l), unit), class = c("margin", "unit"))
 }

R/theme-current.R

@@ -3,11 +3,12 @@
 theme_env <- new.env(parent = emptyenv())
 theme_env$current <- theme_gray()
 
-#' Get, set and update themes
+#' Get, set, and modify the active theme
 #'
+#' The current/active theme is automatically applied to every plot you draw.
 #' Use \code{theme_get} to get the current theme, and \code{theme_set} to
 #' completely override it. \code{theme_update} and \code{theme_replace} are
-#' shorthands for changing individual elements in the current theme.
+#' shorthands for changing individual elements.
 #'
 #' @section Adding on to a theme:
 #'
@@ -29,49 +30,41 @@ theme_env$current <- theme_gray()
 #'
 #' @param ... named list of theme settings
 #' @param e1,e2 Theme and element to combine
+#' @return \code{theme_set}, \code{theme_update}, and \code{theme_replace}
+#'   invisibly return the previous theme so you can easily save it, then
+#'   later restore it.
 #' @seealso \code{\link{+.gg}}
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(mpg, wt)) +
 #'   geom_point()
 #' p
-#' old <- theme_set(theme_bw())
-#' p
-#' theme_set(old)
-#' p
 #'
-#' #theme_replace NULLs out the fill attribute of panel.background,
-#' #resulting in a white background:
-#' theme_get()$panel.background
-#' old <- theme_replace(panel.background = element_rect(colour = "pink"))
-#' theme_get()$panel.background
+#' # Use theme_set() to completely override the current theme.
+#' # Here we have the old theme so we can later restore it.
+#' # Note that the theme is applied when the plot is drawn, not
+#' # when it is created.
+#' old <- theme_set(theme_bw())
 #' p
 #' theme_set(old)
-#'
-#' #theme_update only changes the colour attribute, leaving the others intact:
-#' old <- theme_update(panel.background = element_rect(colour = "pink"))
-#' theme_get()$panel.background
 #' p
-#' theme_set(old)
-#'
-#' theme_get()
-#'
 #'
-#' ggplot(mtcars, aes(mpg, wt)) +
-#'   geom_point(aes(color = mpg)) +
-#'   theme(legend.position = c(0.95, 0.95),
-#'         legend.justification = c(1, 1))
-#' last_plot() +
-#'  theme(legend.background = element_rect(fill = "white", colour = "white", size = 3))
 #'
-#' # Adding on to a theme ----------------------------------------------
-#'
-#' # Compare these results of adding theme objects to other theme objects
-#' add_el <- theme_grey() + theme(text = element_text(family = "Times"))
-#' rep_el <- theme_grey() %+replace% theme(text = element_text(family = "Times"))
+#' # Modifying theme objects -----------------------------------------
+#' # You can use + and %+replace% to modify a theme object.
+#' # They differ in how they deal with missing arguments in
+#' # the theme elements.
 #'
+#' add_el <- theme_grey() +
+#'   theme(text = element_text(family = "Times"))
 #' add_el$text
+#'
+#' rep_el <- theme_grey() %+replace%
+#'   theme(text = element_text(family = "Times"))
 #' rep_el$text
+#'
+#' # theme_update() and theme_replace() are similar except they
+#' # apply directly to the current/active theme.
 theme_get <- function() {
   theme_env$current
 }

R/theme-defaults.r

@@ -1,12 +1,14 @@
-#' ggplot2 themes
+#' Complete themes
 #'
-#' Themes set the general aspect of the plot such as the colour of the
-#' background, gridlines, the size and colour of fonts.
+#' These are complete themes which control all non-data display. Use
+#' \code{\link{theme}} if you just need to tweak the display of an existing
+#' theme.
 #'
 #' @param base_size base font size
 #' @param base_family base font family
 #'
-#' @details \describe{
+#' @details
+#' \describe{
 #'
 #' \item{\code{theme_gray}}{
 #' The signature ggplot2 theme with a grey background and white gridlines,
@@ -43,18 +45,16 @@
 #' @examples
 #' p <- ggplot(mtcars) + geom_point(aes(x = wt, y = mpg,
 #'      colour = factor(gear))) + facet_wrap(~am)
-#'
-#' p
+#' p + theme_gray() # the default
 #' p + theme_bw()
 #' p + theme_linedraw()
 #' p + theme_light()
 #' p + theme_dark()
 #' p + theme_minimal()
 #' p + theme_classic()
 #' p + theme_void()
-#' p + theme_gray() # default theme
-#'
 #' @name ggtheme
+#' @aliases NULL
 NULL
 
 #' @include theme.r

R/theme-elements.r

@@ -1,7 +1,8 @@
 #' Theme elements
 #'
-#' In conjunction with the \link{theme} system, these objects specify the display of
-#' how non-data components of the plot are a drawn.
+#' @description
+#' In conjunction with the \link{theme} system, the \code{element_} functions
+#' specify the display of how non-data components of the plot are a drawn.
 #'
 #' \itemize{
 #'   \item \code{element_blank}: draws nothing, and assigns no space.
@@ -10,16 +11,18 @@
 #'   \item \code{element_text}: text.
 #' }
 #'
+#' \code{rel()} is used to specify sizes relative to the parent,
+#' \code{margins()} is used to specify the margins of elements.
+#'
 #' @param fill Fill colour.
 #' @param colour,color Line/border colour. Color is an alias for colour.
 #' @param size Line/border size in mm; text size in pts.
 #' @param inherit.blank Should this element inherit the existence of an
-#' element_blank among its parents? If \code{TRUE} the existence of a blank
-#' element among its parents will cause this element to be blank as well. If
-#' \code{FALSE} any blank parent element will be ignored when calculating final
-#' element state.
-#' @name element
-#' @return An S3 object of class \code{element}.
+#'   \code{element_blank} among its parents? If \code{TRUE} the existence of
+#'   a blank element among its parents will cause this element to be blank as
+#'   well. If \code{FALSE} any blank parent element will be ignored when
+#'   calculating final element state.
+#' @return An S3 object of class \code{element}, \code{rel}, or \code{margin}.
 #' @examples
 #' plot <- ggplot(mpg, aes(displ, hwy)) + geom_point()
 #'
@@ -29,17 +32,24 @@
 #' )
 #'
 #' plot + theme(
-#'   axis.text = element_text(colour = "red", size = 12)
+#'   axis.text = element_text(colour = "red", size = rel(1.5))
 #' )
 #'
 #' plot + theme(
-#'   axis.line.x = element_line()
+#'   axis.line = element_line(arrow = arrow())
 #' )
 #'
 #' plot + theme(
-#'   panel.background = element_rect(fill = "grey95"),
-#'   panel.border = element_rect(colour = "grey70", fill = NA, size = 1)
+#'   panel.background = element_rect(fill = "white"),
+#'   plot.margin = margin(2, 2, 2, 2, "cm"),
+#'   plot.background = element_rect(
+#'     fill = "grey90",
+#'     colour = "black",
+#'     size = 1
+#'   )
 #' )
+#' @name element
+#' @aliases NULL
 NULL
 
 #' @export
@@ -117,14 +127,7 @@ element_text <- function(family = NULL, face = NULL, colour = NULL,
 print.element <- function(x, ...) utils::str(x)
 
 
-#' Relative sizing for theme elements
-#'
-#' @param x A number representing the relative size
-#' @examples
-#' df <- data.frame(x = 1:3, y = 1:3)
-#' ggplot(df, aes(x, y)) +
-#'   geom_point() +
-#'   theme(axis.title.x = element_text(size = rel(2.5)))
+#' @rdname element
 #' @export
 rel <- function(x) {
   structure(x, class = "rel")
@@ -135,6 +138,7 @@ print.rel <- function(x, ...) print(noquote(paste(x, " *", sep = "")))
 
 #' Reports whether x is a rel object
 #' @param x An object to test
+#' @keywords internal
 is.rel <- function(x) inherits(x, "rel")
 
 # Given a theme object and element name, return a grob for the element

R/theme.r

@@ -1,10 +1,18 @@
-#' Set theme elements
+#' Modify components of a theme
 #'
-#' Theme elements can inherit properties from other theme elements.
+#' Use \code{theme()} to modify individual components of a theme, allowing
+#' you to control the appearance of all non-data components of the plot.
+#' \code{theme()} only affects a single plot: see \code{\link{theme_update}} if
+#' you want modify the active theme, to affect all subsequent plots.
+#'
+#' @section Theme inheritance:
+#' Theme elements inherit properties from other theme elements.
 #' For example, \code{axis.title.x} inherits from \code{axis.title},
 #' which in turn inherits from \code{text}. All text elements inherit
 #' directly or indirectly from \code{text}; all lines inherit from
 #' \code{line}, and all rectangular objects inherit from \code{rect}.
+#' This means that you can modify the appearance of multiple elements by
+#' setting a single high-level component.
 #'
 #' @param line all line elements (\code{element_line})
 #' @param rect all rectangular elements (\code{element_rect})
@@ -155,7 +163,6 @@
 #'
 #' @seealso
 #'   \code{\link{+.gg}} and \code{\link{\%+replace\%}},
-#'   \code{\link{rel}} for details of relative sizing,
 #'   \code{\link{element_blank}}, \code{\link{element_line}},
 #'   \code{\link{element_rect}}, and \code{\link{element_text}} for
 #'   details of the specific theme elements.
@@ -564,6 +571,7 @@ combine_elements <- function(e1, e2) {
 #' Reports whether x is a theme object
 #' @param x An object to test
 #' @export
+#' @keywords internal
 is.theme <- function(x) inherits(x, "theme")
 
 #' @export

_pkgdown.yml

@@ -110,7 +110,7 @@ reference:
   - label_bquote
 
 - title: Coordinate systems
-  desc:
+  desc: >
     The coordinate system determines how the `x` and `y` aesthetics combine
     to position elements in the plot. The default coordinate system is
     Cartesian (`coord_cartesian()`), which can be tweaked with `coord_map()`,
@@ -125,16 +125,18 @@ reference:
   - coord_trans
 
 - title: Themes
+  desc: >
+    Themes control the display of all non-data elements of the plot. You
+    can override all settings with a complete theme like `theme_bw()`, or
+    choose to tweak individual settings by using `theme()` and the `element_`
+    functions. Use `theme_set()` to modify the active theme, affecting all
+    future plots.
   contents:
-  - ggtheme
   - theme
+  - theme_bw
   - theme_update
-  - element
-  - rel
-  - is.rel
-  - is.theme
+  - element_line
   - margin
-  - graphical-units
 
 - title: Programming with ggplot2
   contents: