refactor docs to use docstrings and have a gallery

README.md

@@ -23,14 +23,27 @@ If you use **Gadfly** in a publication please consider citing it: [![DOI][citati
 - Interactivity like panning, zooming, toggling powered by [Snap.svg](http://snapsvg.io/)
 - Supports a large number of common plot types
 
-## Installation
+## Installation & Quickstart
 
 **Gadfly** is registered on `METADATA.jl` and so can be installed using `Pkg.add`.
 
 ```julia
 Pkg.add("Gadfly")
 ```
 
+To create a plot it's as simple as:
+
+```julia
+using Gadfly
+plot(y=[1,2,3])
+```
+
+## Gallery
+
+<div align="center"> <img
+src="https://cdn.rawgit.com/GiovineItalia/Gadfly.jl/master/docs/src/assets/gallery.png"
+alt="Gadfly Gallery" width="1024"></img> </div>
+
 ## Documentation
 
 - [**STABLE**][docs-stable-url] &mdash; **most recently tagged version of the documentation.**

docs/make.jl

@@ -16,12 +16,20 @@ makedocs(
             "Backends" => "man/backends.md",
             "Themes" => "man/themes.md",
         ],
+        "Gallery" => Any[
+            "Geometries" => "gallery/geometries.md",
+            "Guides" => "gallery/guides.md",
+            #"Statistics" => "gallery/stats.md",
+            #"Coords" => "gallery/coords.md",
+            #"Scales" => "gallery/scales.md",
+            #"Shapes" => "gallery/shapes.md",
+        ],
         "Library" => Any[
-            hide("Geometries" => "lib/geometries.md", load_dir("geoms")),
-            hide("Guides" => "lib/guides.md", load_dir("guides")),
-            hide("Statistics" => "lib/stats.md", load_dir("stats")),
-            hide("Coords" => "lib/coords.md", load_dir("coords")),
-            hide("Scales" => "lib/scales.md", load_dir("scales")),
+            "Geometries" => "lib/geometries.md",
+            "Guides" => "lib/guides.md",
+            "Statistics" => "lib/stats.md",
+            "Coords" => "lib/coords.md",
+            "Scales" => "lib/scales.md",
             "Shapes" => "lib/shapes.md",
         ],
         "Development" => Any[

docs/src/gallery/geometries.md

@@ -0,0 +1,94 @@
+# Geometries
+
+## Geom.point
+
+```@setup 1
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth", Geom.point)
+```
+
+```@example
+# Binding categorial data to the color aesthetic
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
+     color="Species", Geom.point)
+```
+
+```@example
+# Binding continuous data to the color aesthetic
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
+     color="PetalLength", Geom.point)
+```
+
+```@example
+# Binding categorial data to x
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(dataset("lattice", "singer"), x="VoicePart", y="Height", Geom.point)
+```
+
+```@example
+# Binding categorical data to the shape aesthetic
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
+        shape="Species", color="Species", Geom.point)
+```
+
+```@example
+# Different colored layers
+using Gadfly, Distributions
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+rdata = rand(MvNormal([0,0.],[1 0;0 1.]),100)
+bdata = rand(MvNormal([1,0.],[1 0;0 1.]),100)
+plot(layer(x=rdata[1,:], y=rdata[2,:], color=[colorant"red"], Geom.point),
+     layer(x=bdata[1,:], y=bdata[2,:], color=[colorant"blue"], Geom.point))
+```
+
+## Geom.bar
+
+```@example
+using Gadfly, RDatasets
+set_default_plot_size(12cm, 8cm) # hide
+plot(dataset("HistData", "ChestSizes"), x="Chest", y="Count", Geom.bar)
+```
+
+```@example
+using Gadfly, RDatasets
+set_default_plot_size(12cm, 8cm) # hide
+plot(by(dataset("datasets","HairEyeColor"),[:Eye,:Sex], d->sum(d[:Freq])),
+    color="Eye", y="x1", x="Sex",
+    Geom.bar(position=:dodge), Guide.ylabel("Freq"))
+```
+
+```@example
+using Gadfly, RDatasets, DataFrames
+set_default_plot_size(14cm, 8cm) # hide
+D = by(dataset("datasets","HairEyeColor"), [:Eye,:Sex], d->sum(d[:Freq]))
+ rename!(D, :x1, :Frequency)
+palette = ["blue","brown","green","tan"]  # Is there a hazel color?
+
+pa= plot(D, x=:Sex, y=:Frequency, color=:Eye, Geom.bar(position=:stack),
+    Scale.color_discrete_manual(palette...))
+pb= plot(D, x=:Sex, y=:Frequency, color=:Eye, Geom.bar(position=:stack),
+    Scale.color_discrete_manual(palette[4:-1:1]..., order=[4,3,2,1]))
+hstack(pa, pb)
+```
+
+## Geom.line
+
+```@example 1
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm)  # hide
+plot(dataset("lattice", "melanoma"), x="Year", y="Incidence", Geom.line)
+```
+
+```@example 1
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm)  # hide
+plot(dataset("Zelig", "approval"), x="Month",  y="Approve", color="Year", Geom.line)
+```

docs/src/gallery/guides.md

@@ -0,0 +1,50 @@
+# Guides
+
+## Guide.title
+
+```@example
+using Gadfly, RDatasets
+Gadfly.set_default_plot_size(14cm, 8cm)  # hide
+plot(dataset("ggplot2", "diamonds"), x="Price", Geom.histogram,
+    Guide.title("Diamond Price Distribution"))
+```
+
+## Guide.xlabel
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.xlabel("Angle"))
+```
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.xlabel("Angle", orientation=:vertical))
+```
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.xlabel(nothing))
+```
+
+## Guide.ylabel
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.ylabel("cos(x)"))
+```
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.ylabel("cos(x)", orientation=:horizontal))
+```
+
+```@example
+using Gadfly
+Gadfly.set_default_plot_size(14cm, 8cm) # hide
+plot(cos, 0, 2π, Guide.ylabel(nothing))
+```

docs/src/lib/geometries.md

@@ -10,9 +10,8 @@ draw things. For instance, the [Geom.point](@ref) geometry draws points using
 the `x` and `y` aesthetics, while the [Geom.line](@ref) geometry draws lines
 with those same two aesthetics.
 
-## Available Geometries
-
-```@contents
-Pages = map(file -> joinpath("geoms", file), readdir("geoms"))
-Depth = 1
+```@docs
+Geom.point
+Geom.bar
+Geom.line
 ```

docs/src/lib/geoms/geom_bar.md

@@ -4,74 +4,8 @@ Author = "Daniel C. Jones"
 
 # Geom.bar
 
-Draw bar plots. This geometry works on pre-summarized data such as counts. To
-draw histograms from a series of observations, add [Stat.histogram](@ref) to the plot,
-or use the convenient geometry [Geom.histogram](@ref).
-
-## Aesthetics
-
-  * `y`: Height of each bar.
-  * `color` (optional): Group categorically by color.
-
-Either
-
-  * `x`: Position of each bar.
-
-Or
-
-  * `xmin`: Starting x positions for each bar.
-  * `xmax`: End x positions for each bar.
-
-If `x` is given, a bar will be drawn at each x value, specifying both `xmin` and
-`xmax` allows bars of variable width to be drawn.
-
-## Arguments
-
-  * `position`: Either `:stack` or `:dodge`. If the `color` aesthetic is
-    bound this determines how bars of different colors should be arranged:
-    stacked on top of each other, or placed side by side.
-
-  * `orientation`: Either `:vertical` (default) or `:horizontal`. If
-    `:horizontal`, then the required aesthetics are `y` or `ymin/ymax`.
-
 ## Examples
 
-```@setup 1
-using RDatasets
-using Gadfly
-set_default_plot_size(12cm, 8cm)
-```
-
-```@example 1
-plot(dataset("HistData", "ChestSizes"), x="Chest", y="Count", Geom.bar)
-```
-
-```@example 1
-plot(by(dataset("datasets","HairEyeColor"),[:Eye,:Sex], d->sum(d[:Freq])),
-    color="Eye", y="x1", x="Sex",
-    Geom.bar(position=:dodge), Guide.ylabel("Freq"))
-```
-
-```@setup 2
-using RDatasets
-using DataFrames, Gadfly
-set_default_plot_size(14cm, 8cm)
-```
-
-```@example 2
-D = by(dataset("datasets","HairEyeColor"), [:Eye,:Sex], d->sum(d[:Freq]))
- rename!(D, :x1, :Frequency)
-# Is there a hazel color?
-palette = ["blue","brown","green","tan"]
-
-pa= plot(D, x=:Sex, y=:Frequency, color=:Eye, Geom.bar(position=:stack),
-    Scale.color_discrete_manual(palette...)
-)
-pb= plot(D, x=:Sex, y=:Frequency, color=:Eye, Geom.bar(position=:stack),
-    Scale.color_discrete_manual(palette[4:-1:1]..., order=[4,3,2,1])
-)
-hstack(pa, pb)
-```
 See [Scale.color_discrete_manual](@ref) for more information.
 
 

docs/src/lib/geoms/geom_line.md

@@ -4,33 +4,7 @@ Author = "Daniel C. Jones"
 
 # Geom.line
 
-## Aesthetics
-
-  * `x`: X-axis position.
-  * `y`: Y-axis position.
-  * `group` (optional): Group categorically.
-  * `color` (optional): Group categorically and indicate by color.
-
-## Arguments
-
-  * `preserve_order`: Default behavior for `Geom.line` is to draw lines between
-    points in order along the x-axis. If this option is true, lines will be
-    drawn between points in the order they appear in the data. `Geom.path()` is
-    `Geom.line(preserve_order=true)`.
 
 
 ## Examples
 
-```@setup 1
-using RDatasets
-using Gadfly
-Gadfly.set_default_plot_size(14cm, 8cm)
-```
-
-```@example 1
-plot(dataset("lattice", "melanoma"), x="Year", y="Incidence", Geom.line)
-```
-
-```@example 1
-plot(dataset("Zelig", "approval"), x="Month",  y="Approve", color="Year", Geom.line)
-```

docs/src/lib/geoms/geom_point.md

@@ -4,56 +4,5 @@ Author = "Daniel C. Jones"
 
 # Geom.point
 
-The point geometry is used to draw various types of scatterplots.
-
-## Aesthetics
-
-  * `x`: X-axis position.
-  * `y`: Y-axis position.
-  * `color` (optional): Point color.  Categorical data will choose maximally distinguishable colors from the LCHab color space.  Continuous data will map onto LCHab as well.  Colors can also be specified explicitly for each data point with a vector of colors of length(x).  A vector of length one specifies the color to use for all points.  Default is Theme.default_color.
-  * `shape` (optional): Point shape.  Categorical data will cycle through Theme.point_shapes.  Shapes can also be specified explicitly for each data point with a vector of shapes of length(x).  A vector of length one specifies the shape to use for all points.  Default is Theme.point_shapes[1].
-  * `size` (optional): Point size.  Categorical data and vectors of Ints will interpolate between Theme.point_size_{min,max}.  A continuous vector of AbstractFloats or Measures of length(x) specifies the size of each data point explicitly.  A vector of length one specifies the size to use for all points.  Default is Theme.point_size.
-
 ## Examples
 
-```@setup 1
-using RDatasets
-using Gadfly
-Gadfly.set_default_plot_size(14cm, 8cm)
-```
-
-```@example 1
-plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth", Geom.point)
-```
-
-```@example 1
-# Binding categorial data to the color aesthetic
-plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
-     color="Species", Geom.point)
-```
-
-```@example 1
-# Binding continuous data to the color aesthetic
-plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
-     color="PetalLength", Geom.point)
-```
-
-```@example 1
-# Binding categorial data to x
-plot(dataset("lattice", "singer"), x="VoicePart", y="Height", Geom.point)
-```
-
-```@example 1
-# Binding categorical data to the shape aesthetic
-plot(dataset("datasets", "iris"), x="SepalLength", y="SepalWidth",
-        shape="Species", color="Species", Geom.point)
-```
-
-```@example 1
-# Different colored layers
-using Distributions
-rdata = rand(MvNormal([0,0.],[1 0;0 1.]),100)
-bdata = rand(MvNormal([1,0.],[1 0;0 1.]),100)
-plot(layer(x=rdata[1,:], y=rdata[2,:], color=[colorant"red"], Geom.point),
-     layer(x=bdata[1,:], y=bdata[2,:], color=[colorant"blue"], Geom.point))
-```