Merge pull request #1173 from bjarthur/bja/docs

update index, tutorial, and manual

REQUIRE

@@ -8,6 +8,7 @@ DataFrames 0.11.4
 DataArrays
 DataStructures
 Distributions
+DocStringExtensions
 Hexagons
 IterTools
 JSON

docs/make.jl

@@ -10,7 +10,7 @@ makedocs(
         "Tutorial" => "tutorial.md",
         "Manual" => Any[
             "Plotting" => "man/plotting.md",
-            "Layers and Stacks" => "man/layers.md",
+            "Compositing" => "man/compositing.md",
             "Backends" => "man/backends.md",
             "Themes" => "man/themes.md",
         ],

docs/src/index.md

@@ -11,37 +11,33 @@ Grammar of
 Graphics](http://www.cs.uic.edu/~wilkinson/TheGrammarOfGraphics/GOG.html).
 It was [Daniel C. Jones'](https://github.com/dcjones) brainchild and is
 now maintained by the community.
+Please consider [citing
+it](https://zenodo.org/record/1284282) if you use it in your work.
 
 ## Package features
 
 - Renders publication quality graphics to SVG, PNG, Postscript, and PDF
 - Intuitive and consistent plotting interface
-- Works with [IJulia](https://github.com/JuliaLang/IJulia.jl) out of the box
+- Works with [Jupyter](http://jupyter.org/) notebooks via [IJulia](https://github.com/JuliaLang/IJulia.jl) out of the box
 - Tight integration with [DataFrames.jl](https://github.com/JuliaStats/DataFrames.jl)
 - Interactivity like panning, zooming, toggling powered by [Snap.svg](http://snapsvg.io/)
 - Supports a large number of common plot types
 
-## Quickstart
+## Installation
 
 The latest release of **Gadfly** can be installed from the Julia REPL prompt with
 
 ```julia
 julia> Pkg.add("Gadfly")
 ```
 
-This installs the package and any missing dependencies. **Gadfly** can be
-loaded with
+This installs the package and any missing dependencies.  From there, the
+simplest of plots can be rendered to your default internet browser with
 
 ```julia
 julia> using Gadfly
+julia> plot(y=[1,2,3])
 ```
 
-Now that you have it loaded, check out the [Tutorial](@ref) for a tour of
+Now that you have it installed, check out the [Tutorial](@ref) for a tour of
 basic plotting and the various manual pages for more advanced usages.
-
-## Credits
-
-Gadfly is predominantly the work of Daniel C. Jones who initiated the project
-and built out most of the infrastructure.  It is now maintained by a community
-of volunteers.  Please consider [citing
-it](https://doi.org/10.5281/zenodo.437192) if you use it in your work.

docs/src/man/backends.md

@@ -4,61 +4,86 @@ Author = "Daniel C. Jones, Tamas Nagy"
 
 # Backends
 
-**Gadfly** supports writing to the SVG and SVGJS backends out of the box. However,
-the PNG, PDF, and PS backends require Julia's bindings to
-[Cairo](https://github.com/JuliaGraphics/Cairo.jl). It can be installed with
+Gadfly supports creating SVG images out of the box through the native Julian
+renderer in [Compose.jl](https://github.com/GiovineItalia/Compose.jl).  The
+PNG, PDF, PS, and PGF formats, however, require Julia's bindings to
+[cairo](https://www.cairographics.org/) and
+[fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/), which can
+be installed with
 
 ```julia
 Pkg.add("Cairo")
+Pkg.add("Fontconfig")
 ```
 
-Additionally, complex layouts involving text are more accurate when
-Pango and Fontconfig are installed.
 
-## Changing the backend
+## Rendering to a file
 
-Drawing to different backends is easy
+In addition to the `draw` interface presented in the [Tutorial](@ref Tutorial):
 
 ```julia
-# define a plot
-myplot = plot(..)
-
-# draw on every available backend
-draw(SVG("myplot.svg", 4inch, 3inch), myplot)
-draw(SVGJS("myplot.svg", 4inch, 3inch), myplot)
-draw(PNG("myplot.png", 4inch, 3inch), myplot)
-draw(PDF("myplot.pdf", 4inch, 3inch), myplot)
-draw(PS("myplot.ps", 4inch, 3inch), myplot)
-draw(PGF("myplot.tex", 4inch, 3inch), myplot)
+p = plot(...)
+draw(SVG("foo.svg", 6inch, 4inch), p)
 ```
 
-!!! note
+one can more succintly use Julia's function chaining syntax:
 
-    The `SVGJS` backend writes SVG with embedded javascript. There are a couple
-    subtleties with using the output from this backend.
+```julia
+p |> SVG("foo.svg", 6inch, 4inch)
+```
+
+If you plan on drawing many figures of the same size, consider
+setting it as the default:
+
+```julia
+set_default_plot_size(6inch, 4inch)
+p1 |> SVG("foo1.svg")
+p2 |> SVG("foo2.svg")
+p3 |> SVG("foo3.svg")
+```
 
-    Drawing to the backend works like any other
 
-    ```julia
-    draw(SVGJS("mammals.js.svg", 6inch, 6inch), p)
-    ```
+## Choosing a backend
 
-    If included with an `<img>` tag, it will display as a static SVG image
+Drawing to different backends is easy.  Simply swap `SVG` for one
+of `SVGJS`, `PNG`, `PDF`, `PS`, or `PGF`:
+
+```julia
+# e.g.
+p |> PDF("foo.pdf")
+```
 
-    ```html
-    <img src="mammals.js.svg"/>
-    ```
 
-    For the interactive javascript features to be enabled, the output either needs
-    to be included inline in the HTML page, or included with an object tag
+## Interactive SVGs
 
-    ```html
-    <object data="mammals.js.svg" type="image/svg+xml"></object>
-    ```
+The `SVGJS` backend writes SVG with embedded javascript. There are a couple
+subtleties with using the output from this backend.
+
+Drawing to the backend works like any other
+
+```julia
+draw(SVGJS("foo.svg", 6inch, 6inch), p)
+```
+
+If included with an `<img>` tag, the output will display as a static SVG image
+though.
+
+```html
+<img src="foo.svg"/>
+```
+
+For the [interactive](@ref Interactivity) javascript features to be enabled, it
+either needs to be included inline in the HTML page, or included with an object
+tag.
+
+```html
+<object data="foo.svg" type="image/svg+xml"></object>
+```
+
+For the latter, a `div` element must be placed, and the `draw` function
+must be passed the id of this element, so it knows where in the
+document to place the plot.
 
-    A `div` element must be placed, and the `draw` function defined in mammals.js
-    must be passed the id of this element, so it knows where in the document to
-    place the plot.
 
 ## IJulia
 
@@ -67,10 +92,6 @@ to [Jupyter](https://jupyter.org/). This includes a browser based notebook
 that can inline graphics and plots. Gadfly works out of the box with IJulia,
 with or without drawing explicity to a backend.
 
-Without a explicit call to `draw` (i.e. just calling `plot`), the D3 backend is used with
-a default plot size. The default plot size can be changed with `set_default_plot_size`.
-
-```julia
-# E.g.
-set_default_plot_size(12cm, 8cm)
-```
+Without an explicit call to `draw` (i.e. just calling `plot` without a trailing
+semicolon), the SVGJS backend is used with the default plot size, which can be
+changed as described above.

docs/src/man/compositing.md

@@ -0,0 +1,140 @@
+```@meta
+Author = "Daniel C. Jones"
+```
+
+# Compositing
+
+Gadfly supports advanced plot composition techniques like faceting, stacking,
+and layering.
+
+
+## Facets
+
+It is easy to make multiple plots that all share a common dataset and axis.
+
+```@example facet
+using Gadfly, RDatasets
+set_default_plot_size(14cm, 8cm) # hide
+iris = dataset("datasets", "iris")
+plot(iris, xgroup="Species", x="SepalLength", y="SepalWidth",
+     Geom.subplot_grid(Geom.point))
+```
+
+[`Geom.subplot_grid`](@ref) can similarly arrange plots vertically, or
+even in a 2D grid if there are two shared axes.
+
+
+## Stacks
+
+To composite plots derived from different datasets, or the same data but
+different axes, a declarative interface is used.  The [Tutorial](@ref Rendering)
+showed how such disparate plots can be horizontally arranged with `hstack`.
+Here we illustrate how to vertically stack them with `vstack` or arrange them
+in a grid with `gridstack`.  These commands allow more customization in regards
+to tick marks, axis labeling, and other plot details than is available with
+[`Geom.subplot_grid`](@ref).
+
+```@setup stacks
+using Gadfly, RDatasets, Compose
+iris = dataset("datasets", "iris")
+```
+
+```@example stacks
+set_default_plot_size(14cm, 16cm) # hide
+fig1a = plot(iris, x=:SepalLength, y=:SepalWidth, Geom.point)
+fig1b = plot(iris, x=:SepalLength, Geom.density,
+             Guide.ylabel("density"), Coord.cartesian(xmin=4, xmax=8))
+vstack(fig1a,fig1b)
+```
+
+`hstack` and `vstack` can be composed to create arbitrary arrangements
+of panels.
+
+```julia
+vstack(hstack(p1,p2),hstack(p3,p4,p5))
+```
+
+If all rows or columns have the same number of panels, it's easiest
+to use `gridstack`.
+
+```julia
+gridstack([p1 p2; p3 p4])
+```
+
+For each of these commands, you can leave a panel empty by passing in a
+`Compose.context()` object.
+
+```@example stacks
+using Compose
+set_default_plot_size(21cm, 16cm) # hide
+fig1c = plot(iris, x=:SepalWidth, Geom.density,
+             Guide.ylabel("density"), Coord.cartesian(xmin=2, xmax=4.5))
+gridstack(Union{Plot,Compose.Context}[fig1a fig1c; fig1b Compose.context()])
+```
+
+Note that in this case the array must be explicitly typed.
+
+Lastly, `title` can be used to add a descriptive string to the top of a stack.
+
+```julia
+title(hstack(p1,p2), "My creative title")
+```
+
+
+## Layers
+
+Draw multiple layers onto the same plot by inputing `Layer` objects to `plot`.
+
+```@setup layer
+using Gadfly, RDatasets, Distributions, StatsBase
+set_default_plot_size(14cm, 8cm)
+iris = dataset("datasets", "iris")
+```
+
+```@example layer
+xdata = sort(iris[:SepalWidth])
+ydata = cumsum(xdata)
+line = layer(x=xdata, y=ydata, Geom.line, Theme(default_color="red"))
+bars = layer(iris, x=:SepalWidth, Geom.bar)
+plot(line, bars)
+```
+
+Note that here we used both the DataFrame and AbstractArrays interface to
+[`layer`](@ref), as well a [`Theme`](@ref) object.  See [Themes](@ref) for more
+information on the latter.
+
+You can also share the same DataFrame across different layers:
+
+```julia
+plot(iris,
+     layer(x=:SepalLength, y=:SepalWidth),
+     layer(x=:PetalLength, y=:PetalWidth, Theme(default_color="red")))
+```
+
+In this case, Gadfly labels the axes with the column names of first layer listed.
+If this is not what is desired, Guides may be explicitly added.
+
+```@example layer
+plot(iris,
+     layer(x=:SepalLength, y=:SepalWidth),
+     layer(x=:PetalLength, y=:PetalWidth, Theme(default_color="red")),
+     Guide.xlabel("length"), Guide.ylabel("width"), Guide.title("Iris data"),
+     Guide.manual_color_key("",["Sepal","Petal"],
+                            [Gadfly.current_theme().default_color,"red"]))
+```
+
+Note that while `layer` can input Geometries, Statistics, and Themes, it can
+not input Scales, Coordinates, or Guides.
+
+The sequence in which layers are drawn, whether they overlap or not, can be
+controlled with the `order` keyword.  Layers with lower order numbers are
+rendered first.  If not specified, the default order for a layer is 0.  Layers
+which have the same order number are drawn in the reverse order in which they
+appear in `plot`'s input arguments.
+
+```julia
+bars = layer(iris, x=:SepalWidth, Geom.bar)
+line = layer(iris, x=xdata, y=ydata, Geom.line, Theme(default_color="red"),
+             order=1)
+plot(bars, line)
+```