Merge pull request #1116 from bjarthur/bja/docs

refactor docs to use docstrings and have a gallery

NEWS.md

@@ -4,16 +4,40 @@ Each release typically has a number of minor bug fixes beyond what is listed her
 
 # Version 0.7.1
 
-  * `Geom.contour`: add support for `DataFrame`. 
+  * `Geom.contour`: add support for `DataFrame` (#1150)
 
 # Version 0.7.0
 
   * Support DataFrames.jl v0.11+ (#1090, #1129, #1131)
   * Change `Theme(grid_strokedash=)` to `Theme(grid_line_style=)` and include in docs (#1106)
   * Add `Geom.ellipse` (#1103)  
+  * Improved SVG interactivity (#1037)
 
-# Version 0.6.1 (WIP)
+# Version 0.6.5
 
+  * ColorKeys inside plot panel (#1087)
+  * Add `Geom.hair` (#1076)
+  * Shape module (#1050)
+  * Boxplot improvements
+
+# Version 0.6.4
+
+  * Regression testing tools (#1020)
+
+# Version 0.6.3
+
+  * Wide format data (#1013)
+
+# Version 0.6.2
+
+  * Add `Geom.rect` (#993)
+  * Add `Geom.vectorfield` (#992)
+  * Unified size, color, shape aesthetics for Geom.point (#991)
+  * {h,v}line point shapes
+
+# Version 0.6.1
+
+  * Add `Stat.smooth` (#983)
 
 # Version 0.6.0
 
@@ -70,12 +94,12 @@ Each release typically has a number of minor bug fixes beyond what is listed her
 
 # Version 0.3.11
 
-  * Options to statically position `Geom.label` labels. (Issue #542)
+  * Options to statically position `Geom.label` labels. (#542)
 
-  * Layers within `Geom.subplot_grid` now work correctly. (Issue #528)
+  * Layers within `Geom.subplot_grid` now work correctly. (#528)
 
   * Add a `background_color` option in `Theme` to change the plot's background
-    color. (Issue #534)
+    color. (#534)
 
   * Rename color scales for increased consistency: `Scale.continuous_color` →
     `Scale.color_continuous` and `Scale.discrete_color` → `Scale.color_discrete`.

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/REQUIRE

@@ -1,7 +1,3 @@
 Documenter
 Cairo
 RDatasets
-Distributions
-DataFrames
-Colors
-Showoff

docs/make.jl

@@ -1,7 +1,5 @@
 using Documenter, Gadfly
 
-load_dir(x) = map(file -> joinpath("lib", x, file), readdir(joinpath(Base.source_dir(), "src", "lib", x)))
-
 makedocs(
     modules = [Gadfly],
     clean = false,
@@ -16,17 +14,27 @@ makedocs(
             "Backends" => "man/backends.md",
             "Themes" => "man/themes.md",
         ],
+        "Gallery" => Any[
+            "Geometries" => "gallery/geometries.md",
+            "Guides" => "gallery/guides.md",
+            "Statistics" => "gallery/statistics.md",
+            "Coordinates" => "gallery/coordinates.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")),
+            "Gadfly" => "lib/gadfly.md",
+            "Geometries" => "lib/geometries.md",
+            "Guides" => "lib/guides.md",
+            "Statistics" => "lib/statistics.md",
+            "Coordinates" => "lib/coordinates.md",
+            "Scales" => "lib/scales.md",
             "Shapes" => "lib/shapes.md",
         ],
         "Development" => Any[
             "Rendering Pipeline" => "dev/pipeline.md",
             "Regression Testing" => "dev/regression.md",
+            "Relationship with Compose.jl" => "dev/compose.md",
         ]
     ]
 )

docs/src/dev/compose.md

@@ -0,0 +1,14 @@
+```@meta
+Author = "Ben Arthur"
+```
+# Relationship with Compose.jl
+
+Gadfly and Compose are tightly intertwined.  As such, if you want to checkout
+the master branch of Gadfly to get the latest features and bug fixes, you'll
+likely also need to checkout Compose.
+
+Moreover, if you're a contributor, you should probably tag releases of Gadfly
+and Compose simultaneously, and ideally submit a single PR to METADATA containing
+both.  It is for this reason that neither uses
+[attobot](https://github.com/attobot/attobot), as it has no mechanism to do
+this.

docs/src/dev/pipeline.md

@@ -46,10 +46,10 @@ The specification of each layer has
 
 All layers of a plot share the same
 
-- [Coordinates](@ref) for the geometry (e.g. cartesian, polar, etc.)
-- axis [Scales](@ref) (e.g. loglog, semilog, etc.)
-- plot-wise [Statistics](@ref) (optional) to be applied to all layers
-- [Guides](@ref)
+- [Coordinates](@ref lib_coord) for the geometry (e.g. cartesian, polar, etc.)
+- axis [Scales](@ref lib_scale) (e.g. loglog, semilog, etc.)
+- plot-wise [Statistics](@ref lib_stat) (optional) to be applied to all layers
+- [Guides](@ref lib_guide)
 
 A full plot specification must describe these shared elements as well as all the layer specifications.
 In the example above, we see that only the data source, statistics, geometry, and mapping are specified.
@@ -75,11 +75,11 @@ Once a full plot specification is filled out, the rendering process proceeds as
 
 1. For each layer in the plot, we first map subsets of the data source to a `Data` object. The `Price` and `Cut` columns of the `diamond` dataset are mapped to the `:x` and `:color` fields of `Data`, respectively.
 
-2. Scales are applied to the data to obtain plottable aesthetics. [Scale.x_continuous](@ref) keeps the values of `df[:Price]` unchanged, while [Scale.color_discrete_hue](@ref) maps the unique elements of `df[:Cut]` (an array of strings) to actual color values.
+2. Scales are applied to the data to obtain plottable aesthetics. [`Scale.x_continuous`](@ref) keeps the values of `df[:Price]` unchanged, while [`Scale.color_discrete_hue`](@ref) maps the unique elements of `df[:Cut]` (an array of strings) to actual color values.
 
-3. The aesthetics are transformed by layer-wise and plot-wise statistics, in order. [Stat.histogram](@ref) replaces the `x` field of the aesthetics with bin positions, and sets the `y` field with the corresponding counts.
+3. The aesthetics are transformed by layer-wise and plot-wise statistics, in order. [`Stat.histogram`](@ref) replaces the `x` field of the aesthetics with bin positions, and sets the `y` field with the corresponding counts.
 
-4. Using the position aesthetics from all layers, we create a Compose context with a coordinate system that fits the data to screen coordinates. [Coord.cartesian](@ref) creates a Compose context that maps a vertical distance of `3000` counts to about two inches in the rendered plot.
+4. Using the position aesthetics from all layers, we create a Compose context with a coordinate system that fits the data to screen coordinates. [`Coord.cartesian`](@ref) creates a Compose context that maps a vertical distance of `3000` counts to about two inches in the rendered plot.
 
 5. Each layer renders its own geometry.
 

docs/src/dev/regression.md

@@ -5,13 +5,13 @@ Author = "Ben Arthur"
 
 Running `Pkg.test("Gadfly")` evaluates all of the files in
 `Gadfly/test/testscripts`.  Any errors or warnings are printed to the REPL.  In
-addition, the figures that are produced are put into either the `gennedoutput/`
-or `cachedoutput/` sub-directories.  Nominally, the former represents the
+addition, the figures that are produced are put into either the `devel-output/`
+or `master-output/` sub-directories.  Nominally, the former represents the
 changes in a pull request while the latter are used for comparison.
 Specifically, `runtests.jl` examines the currently checked out git commit, and
-sets the output directory to `cachedoutput/` if it is the HEAD of the master
+sets the output directory to `master-output/` if it is the HEAD of the master
 branch or if it is detached.  Otherwise, it assumes you are at the tip of a
-development branch and saves the figures to `gennedoutput/`.  After running the
+development branch and saves the figures to `devel-output/`.  After running the
 tests on both of these branches, executing `compare_examples.jl` displays
 differences between the new and old figures.  This script can dump a diff of
 the files to the REPL, open both figures for manual comparison, and/or, for SVG
@@ -27,7 +27,4 @@ So the automated regression analysis workflow is then as follows:
 5. checkout master,
 6. `Pkg.test` again,
 7. `Pkg.add("ArgParse")` and, for B&W images, Cairo, Fontconfig, Rsvg, and Images as well,
-8. check for differences with `julia test/compare_examples.jl [--diff] [--two]
-[--bw] [-h] [filter]`.  For example, `julia test/compare_examples.jl -bw
-.js.svg` will show black and white images hightlighting the differences between
-the svg test images.
+8. check for differences with `julia test/compare_examples.jl [--diff] [--two] [--bw] [-h] [filter]`.  For example, `julia test/compare_examples.jl --bw .js.svg` will show black and white images highlighting the differences between the svg test images.

docs/src/gallery/coordinates.md

@@ -0,0 +1,9 @@
+# Coordinates
+
+## [`Coord.cartesian`](@ref)
+
+```@example
+using Gadfly
+set_default_plot_size(14cm, 8cm)
+plot(sin, 0, 20, Coord.cartesian(xmin=2π, xmax=4π, ymin=-2, ymax=2))
+```