documenter docs

Author: joshday

docs/make.jl

@@ -9,8 +9,8 @@ makedocs(
     ),
     pages = [
         "index.md",
+        "plotly_basics.md",
         "templates.md",
-        "traces.md"
     ]
 )
 

docs/src/plotly_basics.md

@@ -0,0 +1,49 @@
+# Plotly.js Basics
+
+Plotly.js is a JavaScript library that allows you to create interactive plots in the browser.
+
+PlotlyLight provide a lightweight interface over the Javascript, so it is worthwhile to learn how the Plotly.js library works.
+
+## What is a Plot?
+
+The core JS function that generates a plot is `Plotly.newPlot(data, layout, config)`, where `data` is a JSON array of objects and `layout`/`config` are JSON objects.  Each element of `data` is called a **trace** (data along with specifications on how to plot it).
+
+!!! note "Plotly.js Schema"
+    The Plotly.js specification is available as a [JSON schema](https://json-schema.org) (raw JSON [here](https://api.plot.ly/v2/plot-schema?format=json&sha1=%27%27)).
+
+    PlotlyLight includes this schema as `PlotlyLight.plotly.schema` if you wish to investigate it.
+
+## What is a Trace?
+
+- A **trace** is a JSON object that specifies how data should be represented in a plot.
+- There are many different trace *types* (e.g. "scatter" for scatterplots, "box" for boxplots).
+
+
+!!! note "Tab Auto-Complete"
+    PlotlyLight's `plot` function enables tab-autocomplete for trace types:
+    ```julia
+    julia> plot.<TAB>
+    # bar                 barpolar            box                 candlestick
+    # carpet              choropleth          choroplethmapbox    cone
+    # contour             contourcarpet       densitymapbox       funnel
+    # funnelarea          heatmap             heatmapgl           histogram
+    # histogram2d         histogram2dcontour  icicle              image
+    # indicator           isosurface          mesh3d              ohlc
+    # parcats             parcoords           pie                 pointcloud
+    # sankey              scatter             scatter3d           scattercarpet
+    # scattergeo          scattergl           scattermapbox       scatterpolar
+    # scatterpolargl      scattersmith        scatterternary      splom
+    # streamtube          sunburst            surface             table
+    # treemap             violin              volume              waterfall
+    ```
+    Alternatively, you can type e.g. `plot(; type="scatter", kw...)`.
+
+
+!!! note "Trace Chaining"
+    PlotlyLight lets you *chain* traces with the dot syntax:
+    ```@example
+    using PlotlyLight  # hide
+    y = randn(20)
+
+    plot.bar(; y).scatter(; y)
+    ```

docs/src/templates.md

@@ -20,75 +20,88 @@ nothing # hide
 
 ```@example templates
 preset.template.none!()
-plt
+plt  # hide
 ```
 
 ## `ggplot2!()`
 
 ```@example templates
 preset.template.ggplot2!()
-plt
+plt  # hide
 ```
 
 ## `gridon!()`
 
 ```@example templates
 preset.template.gridon!()
-plt
+plt  # hide
 ```
 
 ## `plotly!()`
 
 ```@example templates
 preset.template.plotly!()
-plt
+plt  # hide
 ```
 
 ## `plotly_dark!()`
 
 ```@example templates
 preset.template.plotly_dark!()
-plt
+plt  # hide
 ```
 
 ## `plotly_white!()`
 
 ```@example templates
 preset.template.plotly_white!()
-plt
+plt  # hide
 ```
 
 ## `presentation!()`
 
 ```@example templates
 preset.template.presentation!()
-plt
+plt  # hide
 ```
 
 ## `seaborn!()`
 
 ```@example templates
 preset.template.seaborn!()
-plt
+plt  # hide
 ```
 
 ## `simple_white!()`
 
 ```@example templates
 preset.template.simple_white!()
-plt
+plt  # hide
 ```
 
 ## `xgridoff!()`
 
 ```@example templates
 preset.template.xgridoff!()
-plt
+plt  # hide
 ```
 
 ## `ygridoff!()`
 
 ```@example templates
 preset.template.ygridoff!()
-plt
+plt  # hide
+```
+
+## Custom Template
+
+To create your own template, simply provide any `JSON3`-writeable object to `PlotlyLight.settings.layout.template`.  Here's an example:
+
+```@example templates
+my_template = Config()
+my_template.layout.title.text = "This Title Will be in Every Plot!"
+
+PlotlyLight.settings.layout.template = my_template
+
+plt  # hide
 ```

docs/src/traces.md

@@ -33,9 +33,7 @@ Base.@kwdef mutable struct Settings
     layout::Config          = Config()
     config::Config          = Config(responsive=true)
     reuse_preview::Bool     = true
-    height::String          = "100%"
-    width::String           = "100%"
-    style::Dict{String,String} = Dict("display" => "block", "border" => "none", "min-height" => "350px", "min-width" => "350px")
+    style::Dict{String,String} = Dict("display" => "block", "border" => "none", "min-height" => "350px", "min-width" => "350px", "width" => "100%", "height" => "100%")
 end
 settings::Settings = Settings()
 
@@ -95,13 +93,13 @@ function html_page(o::Plot)
             h.meta(name="viewport", content="width=device-width, initial-scale=1"),
             h.meta(name="description", content="PlotlyLight.jl"),
             h.title("PlotlyLight.jl"),
-            h.style("body { margin: 0px; } /* remove scrollbar in iframe */"),
+            h.style("body { padding: 0px; margin: 0px; } /* remove scrollbar in iframe */"),
         ),
         h.body(html_div(o))
     )
 end
-function html_iframe(o::Plot; height=settings.height, width=settings.width, style=settings.style)
-    IFrame(html_page(o); height=height, width=width, style=join(["$k:$v" for (k,v) in style], ';'))
+function html_iframe(o::Plot; style=settings.style)
+    IFrame(html_page(o); style=join(["$k:$v" for (k,v) in style], ';'))
 end
 Base.show(io::IO, ::MIME"text/html", o::Plot) = show(io, MIME"text/html"(), html_iframe(o))
 Base.show(io::IO, ::MIME"juliavscode/html", o::Plot) = show(io, MIME"text/html"(), o)