Merge pull request #933 from jiho/theme_doc

Document all themes together

Author: hadley

R/theme-defaults.r

@@ -1,10 +1,56 @@
-#' A theme with grey background and white gridlines.
+#' ggplot2 themes
+#'
+#' Themes set the general aspect of the plot such as the colour of the
+#' background, gridlines, the size and colour of fonts.
 #'
 #' @param base_size base font size
 #' @param base_family base font family
-#' @aliases theme_gray theme_grey
-#' @export theme_gray theme_grey
-#' @family themes
+#'
+#' @details \describe{
+#'
+#' \item{\code{theme_gray}}
+#' {The signature ggplot2 theme with a grey background and white gridlines,
+#' designed to put the data forward yet make comparisons easy.}
+#'
+#' \item{\code{theme_bw}}
+#' {The classic dark-on-light ggplot2 theme. May work better for presentations
+#' displayed with a projector.}
+#'
+#' \item{\code{theme_linedraw}}
+#' {A theme with only black lines of various widths on white backgrounds,
+#' reminiscent of a line drawings. Serves a purpose similar to \code{theme_bw}.
+#' Note that this theme has some very thin lines (<< 1 pt) which some journals
+#' may refuse.}
+#'
+#' \item{\code{theme_light}}
+#' {A theme similar to \code{theme_linedraw} but with light grey lines and axes,
+#' to direct more attention towards the data.}
+#'
+#' \item{\code{theme_minimal}}
+#' {A minimalistic theme with no background annotations.}
+#'
+#' \item{\code{theme_classic}}
+#' {A classic-looking theme, with x and y axis lines and no gridlines.}
+#'
+#' }
+#'
+#' @examples
+#' p <- ggplot(mtcars) + geom_point(aes(x = wt, y = mpg,
+#'      colour=factor(gear))) + facet_wrap(~am)
+#'
+#' p
+#' p + theme_gray()
+#' p + theme_bw()
+#' p + theme_linedraw()
+#' p + theme_light()
+#' p + theme_minimal()
+#' p + theme_classic()
+#'
+#' @name ggtheme
+NULL
+
+#' @export
+#' @rdname ggtheme
 theme_grey <- function(base_size = 12, base_family = "") {
   theme(
     # Elements in this first block aren't used directly, but are inherited
@@ -59,15 +105,12 @@ theme_grey <- function(base_size = 12, base_family = "") {
     complete = TRUE
   )
 }
+#' @export
+#' @rdname ggtheme
 theme_gray <- theme_grey
 
-
-#' A theme with white background and dark gridlines.
-#'
-#' @param base_size base font size
-#' @param base_family base font family
 #' @export
-#' @family themes
+#' @rdname ggtheme
 theme_bw <- function(base_size = 12, base_family = "") {
   # Starts with theme_grey and then modify some parts
   theme_grey(base_size = base_size, base_family = base_family) %+replace%
@@ -84,21 +127,8 @@ theme_bw <- function(base_size = 12, base_family = "") {
     )
 }
 
-#' A theme with white background and black gridlines.
-#'
-#' @param base_size base font size
-#' @param base_family base font family
 #' @export
-#' @family themes
-#' @examples
-#' p <- ggplot(mtcars) + geom_point(aes(x = wt, y = mpg))
-#' p
-#' # 'classic' dark-on-light theme
-#' p + theme_bw()
-#' # this theme
-#' p + theme_linedraw()
-#' # variation with light box and axes legends
-#' p + theme_light()
+#' @rdname ggtheme
 theme_linedraw <- function(base_size = 12, base_family = "") {
   # Starts with theme_grey and then modify some parts
   theme_grey(base_size = base_size, base_family = base_family) %+replace%
@@ -116,44 +146,27 @@ theme_linedraw <- function(base_size = 12, base_family = "") {
     )
 }
 
-#' A theme with white background and light grey lines
-#'
-#' @param base_size base font size
-#' @param base_family base font family
 #' @export
-#' @family themes
-#' @examples
-#' p <- ggplot(mtcars) + geom_point(aes(x = wt, y = mpg))
-#' p
-#' # 'classic' dark-on-light theme
-#' p + theme_bw()
-#' # this theme
-#' p + theme_light()
-#' # variation with dark box and axes legends
-#' p + theme_linedraw()
+#' @rdname ggtheme
 theme_light <- function(base_size = 12, base_family = "") {
   # Starts with theme_grey and then modify some parts
   theme_grey(base_size = base_size, base_family = base_family) %+replace%
     theme(
-      axis.ticks        = element_line(colour = "grey50", size = 0.25),
+      axis.ticks        = element_line(colour = "grey70", size = 0.25),
       legend.key        = element_rect(fill = "white", colour = "grey50", size = 0.25),
       panel.background  = element_rect(fill = "white", colour = NA),
-      panel.border      = element_rect(fill = NA, colour = "grey50", size = 0.5),
-      panel.grid.major  = element_line(colour = "grey80", size = 0.25),
-      panel.grid.minor  = element_line(colour = "grey92", size = 0.125),
-      strip.background  = element_rect(fill = "grey50", colour = NA),
+      panel.border      = element_rect(fill = NA, colour = "grey70", size = 0.5),
+      panel.grid.major  = element_line(colour = "grey85", size = 0.25),
+      panel.grid.minor  = element_line(colour = "grey93", size = 0.125),
+      strip.background  = element_rect(fill = "grey70", colour = NA),
       strip.text.x      = element_text(colour = "white"),
       strip.text.y      = element_text(colour = "white", angle = -90)
     )
 
 }
 
-#' A minimalistic theme with no background annotations.
-#'
-#' @param base_size base font size
-#' @param base_family base font family
 #' @export
-#' @family themes
+#' @rdname ggtheme
 theme_minimal <- function(base_size = 12, base_family = "") {
   # Starts with theme_bw and then modify some parts
   theme_bw(base_size = base_size, base_family = base_family) %+replace%
@@ -167,12 +180,8 @@ theme_minimal <- function(base_size = 12, base_family = "") {
     )
 }
 
-#' A classic-looking theme, with x and y axis lines and no gridlines.
-#'
-#' @param base_size base font size
-#' @param base_family base font family
 #' @export
-#' @family themes
+#' @rdname ggtheme
 theme_classic <- function(base_size = 12, base_family = ""){
   theme_bw(base_size = base_size, base_family = base_family) %+replace%
     theme(

man/ggtheme.Rd

@@ -0,0 +1,77 @@
+% Generated by roxygen2 (4.0.0): do not edit by hand
+\name{ggtheme}
+\alias{ggtheme}
+\alias{theme_bw}
+\alias{theme_classic}
+\alias{theme_gray}
+\alias{theme_grey}
+\alias{theme_light}
+\alias{theme_linedraw}
+\alias{theme_minimal}
+\title{ggplot2 themes}
+\usage{
+theme_grey(base_size = 12, base_family = "")
+
+theme_gray(base_size = 12, base_family = "")
+
+theme_bw(base_size = 12, base_family = "")
+
+theme_linedraw(base_size = 12, base_family = "")
+
+theme_light(base_size = 12, base_family = "")
+
+theme_minimal(base_size = 12, base_family = "")
+
+theme_classic(base_size = 12, base_family = "")
+}
+\arguments{
+  \item{base_size}{base font size}
+
+  \item{base_family}{base font family}
+}
+\description{
+Themes set the general aspect of the plot such as the colour of the
+background, gridlines, the size and colour of fonts.
+}
+\details{
+\describe{
+
+\item{\code{theme_gray}}
+{The signature ggplot2 theme with a grey background and white gridlines,
+designed to put the data forward yet make comparisons easy.}
+
+\item{\code{theme_bw}}
+{The classic dark-on-light ggplot2 theme. May work better for presentations
+displayed with a projector.}
+
+\item{\code{theme_linedraw}}
+{A theme with only black lines of various widths on white backgrounds,
+reminiscent of a line drawings. Serves a purpose similar to \code{theme_bw}.
+Note that this theme has some very thin lines (<< 1 pt) which some journals
+may refuse.}
+
+\item{\code{theme_light}}
+{A theme similar to \code{theme_linedraw} but with light grey lines and axes,
+to direct more attention towards the data.}
+
+\item{\code{theme_minimal}}
+{A minimalistic theme with no background annotations.}
+
+\item{\code{theme_classic}}
+{A classic-looking theme, with x and y axis lines and no gridlines.}
+
+}
+}
+\examples{
+p <- ggplot(mtcars) + geom_point(aes(x = wt, y = mpg,
+     colour=factor(gear))) + facet_wrap(~am)
+
+p
+p + theme_gray()
+p + theme_bw()
+p + theme_linedraw()
+p + theme_light()
+p + theme_minimal()
+p + theme_classic()
+}
+