update docs, enable doctests (#68)

docs/make.jl

@@ -6,15 +6,14 @@ makedocs(
     modules = [PGFPlotsX],
     format = :html,
     sitename = "PGFPlotsX.jl",
-    doctest = false,
+    doctest = true,
     strict = false,
     pages = Any[
         "Home" => "index.md",
         "Manual" => [
             "man/options.md",
             "man/structs.md",
             "man/save.md",
-            "man/custom_types.md",
             ],
         "Examples" => [
             "examples/coordinates.md",

docs/src/examples/coordinates.md

@@ -35,7 +35,8 @@ savefigs("coordinates-simple", ans) # hide
 
 ![](coordinates-simple.svg)
 
-Use `xerror`, `xerrorplus`, `xerrorminus`, `yerror` etc for error bars.
+Use `xerror`, `xerrorplus`, `xerrorminus`, `yerror` etc. for error bars.
+
 ```@example pgf
 x = linspace(0, 2π, 20)
 @pgf Plot(

docs/src/index.md

@@ -2,24 +2,27 @@
 
 ## Introduction
 
-*PGFPlotsX* is a Julia package to generate publication quality figures using the LaTeX library PGFPlots.
-
-It is similar in spirit to the package [PGFPlots.jl](https://github.com/sisl/PGFPlots.jl) but it
-tries to have a very close mapping to the PGFPlots API as well as minimize the number of dependencies.
-The fact that the syntax is similar to the TeX version means that examples from Stack Overflow and the PGFPlots manual can
-easily be incorporated in the Julia code.
-
-Documentation is a WIP but a quite extensive set of examples can be found at the [PGFPlotsXExamples repo](https://github.com/KristofferC/PGFPlotsXExamples).
+*PGFPlotsX* is a Julia package for creating publication quality figures using the LaTeX library [PGFPlots](http://pgfplots.sourceforge.net/)
+as the backend. PGFPlots has [extensive documentation (pdf)](http://pgfplots.sourceforge.net/pgfplots.pdf)
+and a rich database of answered questions on places like [stack overflow](https://stackoverflow.com/questions/tagged/pgf)
+and [tex.stackexchange](https://tex.stackexchange.com/questions/tagged/pgfplots).
+In order to take advantage of this, the syntax in PGFPlotsX is similar to the one written in `.tex`.
+It is therefore, usually, easy to translate a PGFPlots example written in `.tex` to PGFPlotsX Julia code.
+The advantage of using *PGFPlotsX.jl* over writing raw latex code is that it is possible to use Julia objects directly in the figures. Furthermore, the figures can be previewed in notebooks and IDE's, like julia-vscode and Atom-Juno.
+It is for example possible to directly use a `DataFrame` from [*DataFrames.jl*](https://github.com/JuliaData/DataFrames.jl) as a PGFPlots `table`.
 
 ## Installation
 
 ```julia-repl
 Pkg.add("PGFPlotsX")
 ```
 
-To show figures in svg (like is done by default in Jupyter notebooks) you need `pdf2svg`. On Ubuntu, you can get this by running `sudo apt-get install pdf2svg` and on RHEL/Fedora by running `sudo dnf install pdf2svg`. On Windows, you can download the binaries from [here](http://www.cityinthesky.co.uk/opensource/pdf2svg/). Be sure to add `pdf2svg` to your path.
+*PGFPlots.jl* requires a latex installation with the PGFPlots package installed.
+We recommend using a latex installation with access to lualatex since it can have significantly better performance than pdflatex.
+
+To generate or preview figures in svg (like is done by default in Jupyter notebooks) `pdf2svg` is required. This can obtained by, on Ubuntu, running `sudo apt-get install pdf2svg`, on RHEL/Fedora `sudo dnf install pdf2svg` and on macOS e.g. `brew install pdf2svg`. On Windows, the binary can be downloaded from [here](http://www.cityinthesky.co.uk/opensource/pdf2svg/); be sure to add `pdf2svg` to the `PATH`.
 
-For saving (or showing) png figures you need `pdftoppm` which should be installed by default on Linux but can otherwise be downloaded [here](http://www.foolabs.com/xpdf/download.html).
+For png figures `pdftoppm` is required. This should by default on Linux and on macOS should be available after running `brew install poppler`. It is also available in the *Xpdf tools* archive which can be downloaded [here](http://www.foolabs.com/xpdf/download.html).
 
 !!! note
-    If you installed a new latex engine, `pdf2svg` or `pdftoppm` after you installed *PGFPlotsX* you need to run `Pkg.build("PGFPlotsX")` for this to be reflected.
+    If you installed a new latex engine, `pdf2svg` or `pdftoppm` after you installed *PGFPlotsX* you need to run `Pkg.build("PGFPlotsX")` for this to be reflected. The output from `Pkg.build` should tell you what latex engines and figure converters it finds.

docs/src/man/options.md

@@ -1,7 +1,12 @@
 # Defining options
 
+```@meta
+DocTestSetup = quote
+    using PGFPlotsX
+end
+```
 
-In PGFPlots, options are given as a list of keys that might have corresponding values
+In PGFPlots, options are given as a list of keys, that might have corresponding values,
 inside of two square brackets e.g.
 
 ```tex
@@ -10,11 +15,7 @@ inside of two square brackets e.g.
 \end{axis}
 ```
 
-This section shows the method for which to set and retrieve such options.
-
-!!! note
-    Sometimes examples are more telling than documentation so please check out [the examples](https://github.com/KristofferC/PGFPlotsXExamples).
-
+This section shows the method for which to set and retrieve such options in Julia.
 
 ## Setting options when constructing an object
 
@@ -24,12 +25,12 @@ When constructing an object (like a `Plot`), options to that object can be enter
 where a string represents a key without a value (e.g. `"very thick"`) and a pair represents a key/value option, (e.g. `"samples" => 50`).
 This works well when the options are few and there is only one level of options in the object.
 
-```julia-repl
-julia> c = Coordinates([1,2,3], [2, 4, 8]);
+```jldoctest p1
+julia> c = Coordinates([1, 2, 3], [2, 4, 8]);
 
-julia> p = Plot(c, "very thick", "mark" => "halfcircle")
+julia> p = Plot(c, "very thick", "mark" => "halfcircle");
 
-julia> print_tex(p); # print_tex is typically not called from user code
+julia> print_tex(p); # print_tex can be used to preview the generated .tex
 \addplot+[very thick, mark={halfcircle}]
         coordinates {
         (1, 2)
@@ -46,33 +47,34 @@ Instead, we provide a macro `@pgf` so that options can be entered similarly to h
 
 The previous example is then written as
 
-```julia-repl
-@pgf Plot(c,
-    {
-        very_thick,
-        mark = "halfcircle"
-    })
+```jldoctest p1
+julia> @pgf Plot(
+           {
+               very_thick,
+               mark = "halfcircle"
+           },
+           c);
 ```
 
 A more complicated example is:
 
-```julia-repl
-@pgf a = Axis(Plot(c),
-    {
-        "axis background/.style" =
-        {
-            shade,
-            top_color = "gray",
-            bottom_color = "white",
-        },
-        ymode = "log"
-    }
-)
+```jldoctest p1
+julia> @pgf a = Axis(Plot(c),
+           {
+               "axis background/.style" =
+               {
+                   shade,
+                   top_color = "gray",
+                   bottom_color = "white",
+               },
+               ymode = "log"
+           }
+       );
 ```
 
 which is printed as
 
-```julia-repl
+```jldoctest p1
 julia> print_tex(a)
     \begin{axis}[axis background/.style={shade, top color={gray}, bottom color={white}}, ymode={log}]
         \addplot+[]
@@ -89,7 +91,7 @@ The macro can be applied to any type of expression and will be applied to everyt
 that is of the form `{ expr }`.
 
 !!!note
-    * Keys that contain symbols that in Julia are operators (e.g the key `"axis background/.style"`) has to be entered
+    * Keys that contain symbols that in Julia are operators (e.g the key `"axis background/.style"`) have to be entered
       as strings, as in the example above.
 
 ### Transformations
@@ -104,29 +106,26 @@ The following transformations of keys/values are done when the options are writt
 
 It is sometimes convenient to set and get options after an object has been created.
 
-```julia-repl
-julia> c = Coordinates([1,2,3], [2, 4, 8]);
+```jldoctest
+julia> c = Coordinates([1, 2, 3], [2, 4, 8]);
 
-julia> p = Plot(c)
+julia> p = Plot(c);
 
 julia> p["fill"] = "blue";
 
-julia> p["fill"];
+julia> p["fill"]
 "blue"
 
 julia> @pgf p["axis background/.style"] = { shade, top_color = "gray", bottom_color = "white" };
 
 julia> p["axis background/.style"]["top_color"];
-"gray"
 
-julia> p["very thick"] = nothing # Set a value less options;
+julia> p["very thick"] = nothing # Set a value-less options;
 
 julia> delete!(p, "fill");
 
-julia> p
-
 julia> print_tex(p)
-    \addplot+[axis background/.style={shade, top color={gray}, bottom color={white}}, very tick]
+    \addplot+[axis background/.style={shade, top color={gray}, bottom color={white}}, very thick]
         coordinates {
         (1, 2)
         (2, 4)
@@ -137,16 +136,17 @@ julia> print_tex(p)
 
 You can also merge in options that have been separately created using `merge!`
 
-```julia-repl
+```jldoctest
 julia> a = Axis();
 
 julia> @pgf opts =  {xmin = 0, ymax = 1, ybar};
 
-julia> merge!(a, opts)
+julia> merge!(a, opts);
 
 julia> print_tex(a)
     \begin{axis}[xmin={0}, ymax={1}, ybar]
     \end{axis}
 ```
 
 It is then easy to apply for example a "theme" to an axis where the themed is a set of options already saved.
+Just `merge!` the theme into an `Axis`.

docs/src/man/save.md

@@ -15,21 +15,22 @@ To set the dpi of the figures in Juno when using `png`, run `dpi_juno_png(dpi::I
 In the REPL, the figure will be exported to a `pdf` and attempted to be opened in the default `pdf` viewing program.
 If you wish to disable this, run `pgf.enable_interactive(false)`.
 
-## Exporting
+## Exporting to files
 
 Figures can be exported to files using
 
 ```jlcon
 PGFPlotsX.save(filename::String, figure; include_preamble::Bool = true, dpi = 150)
 ```
 
-where the file extension of `filename` determines the file type (can be `.pdf`, `.svg` or `.tex`, or the standalone `tikz` file extensions below), `include_preamble` sets if the preamble should be included in the output (only relevant for `tex` export) and `dpi` determines the dpi of the figure (only relevant for `png` export).
+where the file extension of `filename` determines the file type (can be `pdf`, `svg` or `tex`, or the standalone `tikz` file extensions below), `include_preamble` sets if the preamble should be included in the output (only relevant for `tex` export) and `dpi` determines the dpi of the figure (only relevant for `png` export).
 
 The standalone file extensions `.tikz`, `.TIKZ`, `.TikZ`, `.pgf`, `.PGF` save LaTeX code for a `tikzpicture` environment without a preamble. You can `\input` them directly into a LaTeX document, or use the the [tikzscale](https://www.ctan.org/pkg/tikzscale) LaTeX package for using `\includegraphics` with possible size adjustments.
 
 ## Customizing the preamble
 
-It is common to want to use a custom preamble to add user-defined macros or different packages to the preamble. There are a few ways to do this:
+It is common to use a custom preamble to add user-defined macros or use different packages.
+There are a few ways to do this:
 
 * `push!` strings into the global variable `CUSTOM_PREAMBLE`. Each string in that vector will be inserted in the preamble.
 * Modify the `custom_premble.tex` file in the `deps` folder of the directory of the package. This file is directly spliced into the preamble of the output.
@@ -38,7 +39,7 @@ It is common to want to use a custom preamble to add user-defined macros or diff
 ## Choosing the LaTeX engine used
 
 Thee are two different choices for latex engines, `PDFLATEX`, `LUALATEX`.
-By default, `LUALATEX` is used if it was available during `Pkg.build()`. The active engine can be retrieved with the `latexengine()` function and be set with `latexengine!(engine)` where `engine` is one of the three previously mentioned engines.
+By default, `LUALATEX` is used if it was available during `Pkg.build()`. The active engine can be retrieved with the `latexengine()` function and be set with `latexengine!(engine)` where `engine` is one of the two previously mentioned engines (e.g. `PGFPlotsX.PDFLATEX`).
 
 ## Custom flags