[docs] Full edit review of wording and references. (#511)

Extensive review of all documentation with edits, corrections and explanation.
Updates wording and references alongside general fixes and cleaning up in documentation.

Author: jd-foster

docs/make.jl

@@ -113,10 +113,10 @@ makedocs(
     modules=[PlotlyJS, PlotlyBase],
     linkcheck=true,
     pages=[
-        "Home" => "index.md",
+        "Introduction" => "index.md",
         "User Guide" => [
             "Preliminaries" => "basics.md",
-            "Building Blocks" => "building_traces_layouts.md",
+            "Building blocks" => "building_traces_layouts.md",
             "Putting it together" => "syncplots.md",
             "Working with plots" => "manipulating_plots.md",
             "Contributing" => "contributing.md",

docs/src/basics.md

@@ -1,64 +1,81 @@
-## Basics
+## Preliminaries
 
-[plotly.js][_plotlyjs] figures are constructed by calling the function:
+PlotlyJS.jl is a Julia package that relies on the [plotly.js](https://plotly.com/javascript/) JavaScript library.
+
+In that library, figures are constructed by calling the function:
 
 ```js
 Plotly.newPlot(divid, data, layout, config, frames)
 ```
 
 where
 
-- `divid` is an html `div` element where the plot should appear
-- `data` is an array of JSON objects describing the various `trace`s in the visualization
-- `layout` is a JSON object describing the layout properties of the visualization.
-- `config` is a JSON object describing the configuration properties of the visualization. See more detail [here](https://plotly.com/javascript/configuration-options/)
-- `frames` can contain data and layout objects, which define any changes to be animated, and a traces object that defines which traces to animate.
-
-The `divid` argument is handled automatically by one of the supported
-frontends, so users of this package will mostly be concerned about constructing
-the `data`, `layout`, and (optionally) `config` and `frames` arguments.
-
-For a complete list of traces and their attributes see the [plotly.js chart attribute reference][_plotlyref].
-
-<!-- As of version 0.6.0 of this package you can also view a local version of this
-page that is a bit easier to navigate by calling the `PlotlyJS.docs()` function
-from the Julia prompt. This will open an electron window with a local webpage
-containing a version of that reference page. -->
+- `data` is an array of [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON) objects 
+   describing the various data _traces_ in the visualization (see Note)
+- `layout` is a JSON object describing the presentation properties of the visualization
+- `config` is a JSON object describing the configuration properties of the visualization 
+    (see more detail [here](https://plotly.com/julia/configuration-options/))
+- `frames` can contain data and layout objects, which define any changes to be animated,
+   and a traces object that defines which traces to animate.
+
+The `divid` argument refers to an [html `<div>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/div) 
+to control the plot on a page and is handled automatically by one of the supported
+front-ends. Users of this package will mostly be concerned about constructing
+the `data` and the `layout`, and (optionally) `config` and `frames` arguments.
+
+!!! note
+    A _trace_ is a general term for how data is shown graphically on a plot,
+    whether it is a scatter plot, bar chart, 3D surface, choropleth map or some other plot type.
+    A trace is fundamentally a collection of data and the specifications of how that data should be plotted.
+    For a complete list of traces and their attributes see the
+    [plotly figure reference](https://plotly.com/julia/reference/).
+
+When we want to construct a `Plot` in PlotlyJS.jl for plotting on some display, we will usually have
+at least one trace `tr` along with a layout object `ly` which we combine together as `Plot(tr, ly)`.
+If we don't have a layout object then a template will supply a default layout for us.
 
 ## Julia types
 
-There are a handful of core Julia types for representing a visualization
+There are a handful of core Julia types for representing a visualization.
 
-These are
+The `data`, `layout`, `frames`, `divid` and `config` fields of the `Plot` type, shown below,
+map to the arguments to the `Plotly.newplot` function.
+These types are defined in the PlotlyBase.jl package (a dependency of PlotlyJS.jl).
+These are shown (in a much simplified form) here:
 
 ```julia
 abstract type AbstractTrace end
 abstract type AbstractLayout end
 
-mutable struct GenericTrace{T <: AbstractDict{Symbol,Any}} <: AbstractTrace
-    fields::T
+mutable struct GenericTrace <: AbstractTrace
+    fields::Dict{Symbol,Any}
 end
 
-mutable struct Layout{T <: AbstractDict{Symbol,Any}} <: AbstractLayout
-    fields::T
-    subplots::_Maybe{Subplots}
+mutable struct Layout <: AbstractLayout
+    fields::Dict{Symbol,Any}
+    subplots::Subplots
 end
 
-mutable struct PlotlyFrame{T <: AbstractDict{Symbol,Any}} <: AbstractPlotlyAttribute
-    fields::T
+mutable struct PlotlyFrame <: AbstractPlotlyAttribute
+    fields::Dict{Symbol,Any}
 end
 
-mutable struct Plot{TT<:AbstractVector{<:AbstractTrace},TL<:AbstractLayout,TF<:AbstractVector{<:PlotlyFrame}}
-    data::TT
-    layout::TL
+mutable struct PlotConfig
+    scrollZoom::Union{Nothing,Bool} = true
+    editable::Union{Nothing,Bool} = false
+    staticPlot::Union{Nothing,Bool} = false
+...
+end
+
+mutable struct Plot
+    data::Vector{<:AbstractTrace}
+    layout::AbstractLayout
+    frames::Vector{<:PlotlyFrame}
     divid::UUID
     config::PlotConfig
-    frames::TF
 end
 ```
 
-The `data`, `layout`, `divid`, `config`, and `frames` fields of the `Plot` type map 1-1 to the arguments to the `Plotly.newplot` function.
-
-
-[_plotlyjs]: https://plotly.com/javascript/
-[_plotlyref]: https://plotly.com/julia/reference/
+The `data` field of the `Plot` type can be constructed from a single trace or a vector of multiple traces.
+Each trace is itself made up of a `Dict` type holding information about the type of trace
+and its data along with attributes for customising the plotting of that data.