Rewrite Plot and axis-like types.

This is a step towards fixing #44 (almost there!).

1. New user-facing plot/plot3 constructor is

```julia
Plot([incrementa], [options], data, trailing...)
```
and similarly for `Plot3`.

`incremental` defaults to `false`, as this seems to be the most common
use case.

Some validation is done on `data` (checking for type).

This removes the `label` kwarg, and allows us to close #16. Examples
now recommend an explicit `\addlegendentry`.

Docstrings are added for everything, and examples are rewritten
accordingly.

2. Axis-like code cleaned up a bit with macros. Variations on log axes
added. Explicitly document that strings are emitted as is.

3. GroupPlot rewritten, allow multiple plots and empty \nextgroupplot,
two examples added, one from the manual and one for multiple plots.

4. Replaced random examples with deterministic ones, perhaps stick to
this and close #63? Minor indentation issues fixed.

5. Minor fixes for testing framework.

docs/make.jl

@@ -19,6 +19,7 @@ makedocs(
         "Examples" => [
             "examples/coordinates.md",
             "examples/tables.md",
+            "examples/axislike.md",
             "examples/gallery.md",
             "examples/juliatypes.md"
         ]

docs/src/examples/axislike.md

@@ -0,0 +1,37 @@
+# Axis-like objects
+
+```@setup pgf
+using PGFPlotsX
+savefigs = (figname, obj) -> begin
+    PGFPlotsX.save(figname * ".pdf", obj)
+    run(`pdf2svg $(figname * ".pdf") $(figname * ".svg")`)
+    PGFPlotsX.save(figname * ".tex", obj);
+    return nothing
+end
+```
+------------------------
+
+```@example pgf
+x = linspace(0, 2*pi, 100)
+@pgf GroupPlot(
+    {
+        group_style =
+        {
+            group_size="2 by 1",
+            xticklabels_at="edge bottom",
+            yticklabels_at="edge left"
+        },
+        no_markers
+    },
+    {},
+    Plot(true, Table(x, sin.(x))),
+    Plot(true, Table(x, sin.(x .+ 0.5))),
+    {},
+    Plot(true, Table(x, cos.(x))),
+    Plot(true, Table(x, cos.(x .+ 0.5))))
+savefigs("groupplot-multiple", ans) # hide
+```
+
+[\[.pdf\]](groupplot-multiple.pdf), [\[generated .tex\]](groupplot-multiple.tex)
+
+![](groupplot-multiple.svg)

docs/src/examples/coordinates.md

@@ -80,8 +80,7 @@ f(x, y) = (1 - x)^2 + 100*(y - x^2)^2
     {
         surf,
     },
-    Coordinates(x, y, f.(x, y'));
-    incremental = false
+    Coordinates(x, y, f.(x, y'))
 )
 savefigs("coordinates-3d-matrix", ans) # hide
 ```
@@ -104,8 +103,7 @@ y = linspace(-0.5, 3, 50)
             surf,
             shader = "flat",
         },
-        Coordinates(x, y, @. √(f(x, y')));
-        incremental = false
+        Coordinates(x, y, @. √(f(x, y')))
     )
 )
 savefigs("coordinates-3d-matrix-heatmap", ans) # hide

docs/src/examples/gallery.md

@@ -77,8 +77,9 @@ savefigs("simple-expression", ans) # hide
         grid = "major",
     },
     [
-        Plot(Expression("-x^5 - 242"); label = "model")
-        Plot(Coordinates(
+        Plot(true, Expression("-x^5 - 242")),
+        raw"\addlegendentry{model}",
+        Plot(true, Coordinates(
             [
                 (-4.77778,2027.60977),
                 (-3.55556,347.84069),
@@ -89,8 +90,9 @@ savefigs("simple-expression", ans) # hide
                 (2.55556,-341.40638),
                 (3.77778,-1169.24780),
                 (5.00000,-3269.56775),
-            ];
-        ); label = "estimate")
+            ]
+        )),
+        raw"\addlegendentry{estimate}"
     ]
 )
 savefigs("cost-gain", ans) # hide
@@ -305,3 +307,37 @@ savefigs("mesh-scatter", ans) # hide
 
 ![](mesh-scatter.svg)
 
+------------------------
+
+```@example pgf
+# this is an imitation of the figure in the manual, as we generate the data
+x = linspace(0, 10, 100)
+@pgf plot = Plot({very_thick}, Table(x = x, y = @. (sin(x * 8) + 1) * 4 * x))
+@pgf GroupPlot(
+    {
+        group_style =
+        {
+            group_size="2 by 2",
+            horizontal_sep="0pt",
+            vertical_sep="0pt",
+            xticklabels_at="edge bottom"
+        },
+        xmin = 0,
+        ymin = 0,
+        height = "3.7cm",
+        width = "4cm",
+        no_markers
+    },
+    nothing,
+    {xmin=5, xmax=10, ymin=50, ymax=100},
+    plot,
+    {xmax=5, ymax=50},
+    plot,
+    {xmin=5, xmax=10, ymax=50, yticklabels={}},
+    plot)
+savefigs("groupplot-nested", ans) # hide
+```
+
+[\[.pdf\]](groupplot-nested.pdf), [\[generated .tex\]](groupplot-nested.tex)
+
+![](groupplot-nested.svg)

docs/src/examples/juliatypes.md

@@ -24,13 +24,14 @@ using Colors
 axis = Axis()
 @pgf for (i, col) in enumerate(distinguishable_colors(10))
     offset = i * 50
-    p = Plot(Expression("exp(-(x-$μ)^2 / (2 * $σ^2)) / ($σ * sqrt(2*pi)) + $offset"),
-    {
-        color = col,
-        domain = "-3*$σ:3*$σ",
-        style = { ultra_thick },
-        samples = 50
-    }; incremental = false)
+    p = Plot(
+        {
+            color = col,
+            domain = "-3*$σ:3*$σ",
+            style = { ultra_thick },
+            samples = 50
+        },
+        Expression("exp(-(x-$μ)^2 / (2 * $σ^2)) / ($σ * sqrt(2*pi)) + $offset"))
     push!(axis, p)
 end
 axis
@@ -45,15 +46,13 @@ Using a colormap
 
 ```@example pgf
 using Colors
-@pgf begin
-p = Plot3(
-    Expression("cos(deg(x)) * sin(deg(y))"),
+p = @pgf Plot3(
     {
         surf,
         point_meta = "y",
         samples = 13
-    };
-    incremental = false
+    },
+    Expression("cos(deg(x)) * sin(deg(y))")
 )
 colormaps = ["Blues", "Greens", "Oranges", "Purples"]
 td = TikzDocument()
@@ -63,13 +62,11 @@ end
 
 tp = TikzPicture("scale" => 0.5)
 push!(td, tp)
-gp = GroupPlot({ group_style = {group_size = "2 by 2"}})
+gp = @pgf GroupPlot({ group_style = {group_size = "2 by 2"}})
 push!(tp, gp)
 
 for cmap in colormaps
-    push!(gp, p, { colormap_name = cmap })
-end
-
+    @pgf push!(gp, { colormap_name = cmap }, p)
 end
 savefigs("colormap", td) # hide
 ```
@@ -108,12 +105,13 @@ df = dataset("datasets", "iris") # load the dataset
             {
                 x = "SepalLength",
                 y = "SepalWidth",
-                meta = "Species" },
+                meta = "Species"
+            },
             df, # <--- Creating a Table from a DataFrame
         )
     ),
-    Legend(["Setosa", "Versicolor", "Virginica"])
-    ]
+     Legend(["Setosa", "Versicolor", "Virginica"])
+     ]
 )
 savefigs("dataframes", ans) # hide
 ```
@@ -133,11 +131,10 @@ x = 0.0:0.1:2π
 y = 0.0:0.1:2π
 f = (x,y) -> sin(x)*sin(y)
 @pgf Plot({
-                      contour_prepared,
-                      very_thick
-                  },
-                  Table(contours(x, y, f.(x, y'), 6));
-                  incremental = false)
+        contour_prepared,
+        very_thick
+    },
+    Table(contours(x, y, f.(x, y'), 6)))
 savefigs("contour", ans) # hide
 ```
 
@@ -151,17 +148,18 @@ savefigs("contour", ans) # hide
 
 ```@example pgf
 using StatsBase: Histogram, fit
-Axis(Plot(Table(fit(Histogram, randn(100), closed = :left));
-                  incremental = false),
-         @pgf {
-             "ybar interval",
-             "xticklabel interval boundaries",
-             xticklabel = raw"$[\pgfmathprintnumber\tick,\pgfmathprintnumber\nexttick)$",
-             "xticklabel style" =
-             {
-                 font = raw"\tiny"
-             }
-         })
+@pgf Axis(
+    {
+        "ybar interval",
+        "xticklabel interval boundaries",
+        xmajorgrids = false,
+        xticklabel = raw"$[\pgfmathprintnumber\tick,\pgfmathprintnumber\nexttick)$",
+        "xticklabel style" =
+        {
+            font = raw"\tiny"
+        },
+    },
+    Plot(Table(fit(Histogram, linspace(0, 1, 100).^3, closed = :left))))
 savefigs("histogram-1d", ans) # hide
 ```
 
@@ -171,7 +169,9 @@ savefigs("histogram-1d", ans) # hide
 
 ```@example pgf
 using StatsBase: Histogram, fit
-h = fit(Histogram, (randn(1000), randn(1000)), closed = :left)
+w = linspace(-1, 1, 100) .^ 3
+xy = vec(tuple.(w, w'))
+h = fit(Histogram, (first.(xy), last.(xy)), closed = :left)
 @pgf Axis(
     {
         view = (0, 90),
@@ -184,9 +184,7 @@ h = fit(Histogram, (randn(1000), randn(1000)), closed = :left)
             shader = "flat",
 
         },
-        Table(h);
-        incremental = false
-    )
+        Table(h))
 )
 savefigs("histogram-2d", ans) # hide
 ```

docs/src/examples/tables.md

@@ -27,7 +27,7 @@ y = sin.(x)
 You can pass these coordinates in unnamed columns:
 
 ```@example pgf
-Plot(Table([x, y]); incremental = false)
+Plot(Table([x, y]))
 savefigs("table-unnamed-columns", ans) # hide
 ```
 
@@ -38,7 +38,7 @@ savefigs("table-unnamed-columns", ans) # hide
 or named columns:
 
 ```@example pgf
-Plot(Table([:x => x, :y => y]); incremental = false)
+Plot(Table([:x => x, :y => y]))
 savefigs("table-named-columns", ans) # hide
 ```
 
@@ -54,8 +54,7 @@ or rename using options:
         x = "a",
         y = "b",
     },
-    Table([:a => x, :b => y]);
-    incremental = false)
+    Table([:a => x, :b => y]))
 savefigs("table-dict-rename", ans) # hide
 ```
 
@@ -79,8 +78,7 @@ z[z .≤ 0] .= -Inf
             surf,
             shader = "flat",
         },
-        Table(x, x, z);
-        incremental = false
+        Table(x, x, z)
     )
 )
 savefigs("table-jump-3d", ans) # hide