fix histogram2d docs, extend library introduction

Author: kMutagene

docs/00_0_basics.fsx

@@ -35,21 +35,30 @@ _This section is WIP._
 
 ### Table of contents
 
+- Library design(#Library-design)
 - [GenericChart](#GenericChart)
 - [Working with GenericCharts](#Working-with-GenericCharts)
     - [Dynamic object style](#Dynamic-object-style)
 
-## GenericChart
-
+## Library design
 
 Plotly.NET is a .NET wrapper for creation of [plotly charts]() written in F#. This means that, under the hood, all functionality creates JSON objects that can be rendered by plotly.
 
+A plotly.js chart consists of 3 objects:
+
+- `data`, which is a collection of `traces` which represent the data and chart type used to visualize the data
+- `layout`, which controls the general chart layout such as axis positions and styles
+- `config` high level properties of the chart like making all chart elements editable or the tool bar on top
+
+These are mirrored in Plotly.NET's central type, `GenericChart`:
+
+## GenericChart
+
 The central type that gets created by all Chart constructors is `GenericChart`, which itself represents either a single chart or a multi chart (as a Discriminate Union type). It looks like this:
 
 *)
 
 (***do-not-eval***)
-[<NoComparison>]
 type GenericChart =
     | Chart of Trace * Layout * Config * DisplayOptions
     | MultiChart of Trace list * Layout * Config * DisplayOptions
@@ -62,23 +71,87 @@ As you can see, a `GenericChart` consists of four top level objects - `Trace` (m
 - `Config` is an object that configures high level properties of the chart like making all chart elements editable or the tool bar on top
 - `DisplayOptions` is an object that contains meta information about how the html document that contains the chart.
 
-## Working with GenericCharts
+### Layers of abstraction
+
+Plotly.NET uses multiple layers of abstractions to generate valid plotly.js JSON objects with different levels of control and complexity:
+
+#### The Chart module
+
+The `Chart` module provides the highest layer of abstraction. Here, plotly.js trace types are broken down to the most common and useful styling options, and combined with common layout settings.
+It also provides composite charts which consist of multiple traces such as `Chart.Range`, which really is a combination of 3 scatter traces.
+
+Here is an example on how to create a simple 2D point chart:
+*)
+
+let pointChart =
+    Chart.Point([1,2; 3,4])
+
+(*** condition: ipynb ***)
+#if IPYNB
+pointChart
+#endif // IPYNB
+
+(***hide***)
+pointChart |> GenericChart.toChartHTML
+(***include-it-raw***)
 
-### Dynamic object style
+(**
+#### The TraceStyle modules
+
+The TraceStyle modules offer access to all parameters supported by plotly.js for the respective trace type. If you want to create a `scatter` trace, you can use the function
+`Trace2D.initScatter`, which will initialize an empty trace of type `scatter` and apply a styling function to it. This function would be `Trace2DStyle.Scatter`, which can apply all scatter related parameters to a trace. 
+In contrast to the `Chart` module, the parameters are named exactly the same as in plotly.js (but in PascalCase). 
+
+To create a GenericChart from a `Trace` object, you can use `GenericChart.ofTraceObject`.
+Compare how many more styling options you have compared to `Chart.Point` above, but also take a look at how more verbose you have to be. 
+You can clearly see the advantages and disadvantages of both approaches.
+*)
+
+let withTraceStyle =
+    Trace2D.initScatter( 
+        Trace2DStyle.Scatter(
+            X = [1; 3],
+            Y = [2; 4]
+        )
+    )
+    |> GenericChart.ofTraceObject true
+
+(*** condition: ipynb ***)
+#if IPYNB
+withTraceStyle
+#endif // IPYNB
 
-Plotly.NET has multiple abstraction layers to work with `GenericChart`s. The prime directive for all functions provided by this library is the construction of valid plotly JSON objects.
+(***hide***)
+withTraceStyle |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+#### Dynamic object
+
+The prime directive for all functions provided by Plotly.NET is the construction of valid plotly JSON objects.
 For this purpose, `Trace`, `Layout`, and `Config` (and many other internal objects) are inheriting from [`DynamicObj`](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET/DynamicObj.fs),
 an extension of `DynamicObject` which makes it possible to set arbitraryly named and typed properties of these objects via the `?` operator.
 
+If you want to exactly mirror a plotly.js tutorial, or want to set properties that for any reason are not abstracted in Plotly.NET, 
+it can be useful to use the power of DynamicObj to set the parameters directly. Just make sure that the property name is exactly the same as in plotly.js (all lowercase)
+
 So if you want to set any kind of property on one of these objects you can do it in a very declarative way like this:
 *)
 
 let myTrace = Trace("scatter") // create a scatter trace
-myTrace?x <- [0;1;2] // set the x property (the x dimension of the data)
-myTrace?y <- [0;1;2] // set the y property (the y dimension of the data)
+myTrace?x <- [0;3] // set the x property (the x dimension of the data)
+myTrace?y <- [2;4] // set the y property (the y dimension of the data)
+
+let withDynObj = GenericChart.ofTraceObject true myTrace
+
+(*** condition: ipynb ***)
+#if IPYNB
+withDynObj
+#endif // IPYNB
 
-GenericChart.ofTraceObject false myTrace // create a generic chart (layout and config are empty objects. When using useDefaults = true, default styling will be applied.)
-|> Chart.show
+(***hide***)
+withDynObj |> GenericChart.toChartHTML
+(***include-it-raw***)
 
 (**
 lets have a look at the trace object that will be created. The relevant section of the html generated with Chart.Show is the following:

docs/04_4_2d-histograms.fsx

@@ -62,7 +62,7 @@ A Histogram2D chart can be created using the `Chart.Histogram2D` or `Chart.Histo
 
 let histogramContour =
     [
-        Chart.Histogram2DContour (x,y,Line=Line.init(Width=0.))
+        Chart.Histogram2DContour (x,y,ContourLine=Line.init(Width=0.))
         Chart.Point(x,y,Opacity=0.3)
     ]
     |> Chart.combine