Update docs to fsdocs 11, add display options docs

Author: kMutagene

.config/dotnet-tools.json

@@ -15,7 +15,7 @@
       ]
     },
     "fsharp.formatting.commandtool": {
-      "version": "9.0.1",
+      "version": "11.1.0",
       "commands": [
         "fsdocs"
       ]

Plotly.NET.sln

@@ -50,29 +50,30 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "reference", "reference", "{
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{60FB82C0-F472-494E-BCF7-7B3C54212406}"
 	ProjectSection(SolutionItems) = preProject
-		docs\1_0_basics.fsx = docs\1_0_basics.fsx
-		docs\1_1_axis-styling.fsx = docs\1_1_axis-styling.fsx
-		docs\1_2_errorbars.fsx = docs\1_2_errorbars.fsx
-		docs\1_3_multiple-charts.fsx = docs\1_3_multiple-charts.fsx
-		docs\1_4_shapes.fsx = docs\1_4_shapes.fsx
+		docs\0_0_basics.fsx = docs\0_0_basics.fsx
+		docs\1_0_axis-styling.fsx = docs\1_0_axis-styling.fsx
+		docs\1_1_errorbars.fsx = docs\1_1_errorbars.fsx
+		docs\1_2_multiple-charts.fsx = docs\1_2_multiple-charts.fsx
+		docs\1_3_shapes.fsx = docs\1_3_shapes.fsx
+		docs\1_4_display-options.fsx = docs\1_4_display-options.fsx
 		docs\2_0_line-scatter-plots.fsx = docs\2_0_line-scatter-plots.fsx
 		docs\2_1_bar-and-column-charts.fsx = docs\2_1_bar-and-column-charts.fsx
 		docs\2_2_area-plots.fsx = docs\2_2_area-plots.fsx
 		docs\2_3_range-plots.fsx = docs\2_3_range-plots.fsx
 		docs\2_4_bubble-charts.fsx = docs\2_4_bubble-charts.fsx
 		docs\2_5_pie-doughnut-charts.fsx = docs\2_5_pie-doughnut-charts.fsx
 		docs\2_6_table.fsx = docs\2_6_table.fsx
+		docs\2_7_heatmaps.fsx = docs\2_7_heatmaps.fsx
 		docs\3_0_3d-scatter-plots.fsx = docs\3_0_3d-scatter-plots.fsx
 		docs\3_1_3d-line-plots.fsx = docs\3_1_3d-line-plots.fsx
 		docs\3_2_3d-surface-plots.fsx = docs\3_2_3d-surface-plots.fsx
 		docs\3_3_3d-mesh-plots.fsx = docs\3_3_3d-mesh-plots.fsx
 		docs\4_0_histograms.fsx = docs\4_0_histograms.fsx
 		docs\4_1_box-plots.fsx = docs\4_1_box-plots.fsx
 		docs\4_2_violin-plots.fsx = docs\4_2_violin-plots.fsx
-		docs\4_3_heatmaps.fsx = docs\4_3_heatmaps.fsx
-		docs\4_4_contour-plots.fsx = docs\4_4_contour-plots.fsx
-		docs\4_5_2d-histograms.fsx = docs\4_5_2d-histograms.fsx
-		docs\4_6_splom.fsx = docs\4_6_splom.fsx
+		docs\4_3_contour-plots.fsx = docs\4_3_contour-plots.fsx
+		docs\4_4_2d-histograms.fsx = docs\4_4_2d-histograms.fsx
+		docs\4_5_splom.fsx = docs\4_5_splom.fsx
 		docs\5_0_choropleth-map.fsx = docs\5_0_choropleth-map.fsx
 		docs\6_0_candlestick.fsx = docs\6_0_candlestick.fsx
 		docs\7_0_polar-charts.fsx = docs\7_0_polar-charts.fsx

docs/1_0_basics.fsx docs/0_0_basics.fsxdocs/1_0_basics.fsx renamed to docs/0_0_basics.fsx

@@ -1,3 +1,13 @@
+(**
+---
+title: Basics 
+category: General
+categoryindex: 1
+index: 1
+---
+*)
+
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,6 +23,10 @@
 open Plotly.NET
 
 (**
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
 # Plotly.NET basics
 
 _This section is WIP._
@@ -25,7 +39,6 @@ _This section is WIP._
 
 ## GenericChart
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=1_0_basics.fsx.ipynb)
 
 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.
 
@@ -35,15 +48,16 @@ The central type that gets created by all Chart constructors is `GenericChart`,
 
 (***do-not-eval***)
 type GenericChart =
-    | Chart of Trace * Layout * Config
-    | MultiChart of Trace list * Layout * Config
+    | Chart of Trace * Layout * Config * DisplayOptions
+    | MultiChart of Trace list * Layout * Config * DisplayOptions
 
 (**
-As you can see, a `GenericChart` consists of three top level objects - `Trace` (multiple of those in the case of a MultiChart) , `Layout`, and `Config`.
+As you can see, a `GenericChart` consists of four top level objects - `Trace` (multiple of those in the case of a MultiChart) , `Layout`, `Config`, and `DisplayOptions`.
 
 - `Trace` is in principle the representation of a dataset on a chart, including for example the data itself, color and shape of the visualization, etc.
 - `Layout` is everything of the chart that is not dataset specifivc - e.g. the shape and style of axes, the chart title, etc.
 - `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
 

docs/1_1_axis-styling.fsx docs/1_0_axis-styling.fsxdocs/1_1_axis-styling.fsx renamed to docs/1_0_axis-styling.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Axis styling
+category: Chart Layout
+categoryindex: 2
+index: 1
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (**
 # Axis styling
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=1_1_axis-styling.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to style chart axes in F#.
 

docs/1_2_errorbars.fsx docs/1_1_errorbars.fsxdocs/1_2_errorbars.fsx renamed to docs/1_1_errorbars.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Error bars
+category: Chart Layout
+categoryindex: 2
+index: 2
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (**
 # Error bars
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=1_3_errorbars.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to add error bars to plots in F#.
 

docs/1_3_multiple-charts.fsx docs/1_2_multiple-charts.fsxdocs/1_3_multiple-charts.fsx renamed to docs/1_2_multiple-charts.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Multicharts and subplots
+category: Chart Layout
+categoryindex: 2
+index: 3
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (**
 # Multicharts and subplots
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=1_3_multiple-charts.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to create charts with multiple subplots in F#.
 

docs/1_4_shapes.fsx docs/1_3_shapes.fsxdocs/1_4_shapes.fsx renamed to docs/1_3_shapes.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Shapes
+category: Chart Layout
+categoryindex: 2
+index: 4
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (** 
 # Shapes
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=1_4_shapes.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to create Shapes and add them to the Charts in F#.
 

docs/1_4_display-options.fsx

@@ -0,0 +1,140 @@
+(**
+---
+title: Display Options
+category: Chart Layout
+categoryindex: 2
+index: 5
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 12.0.3"
+#r "../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Display Options
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+*Summary:* This example shows how to alter the display options that control the html document that contains plotly charts
+
+You can control the html document that gets created via `Chart.Show` with various functions that change a chart's `DisplayOptions`.
+
+Naturally, these full html documents can not be embedded in this documentation page, so images have to suffice in this case.
+
+let's first create some data for the purpose of creating example charts:
+
+*)
+
+open Plotly.NET 
+  
+let x  = [1.; 2.; 3.; 4.; 5.; 6.; 7.; 8.; 9.; 10.; ]
+let y = [2.; 1.5; 5.; 1.5; 3.; 2.5; 2.5; 1.5; 3.5; 1.]
+
+
+(**
+## Chart description
+
+To create a chart description to put below the chart, use `ChartDescription.create` to create the description, and `Chart.WithDescription` 
+to add the description to the chart's display options:
+*)
+
+let description1 =
+    ChartDescription.create "Hello" "F#"
+
+(***do-not-eval***)
+let desc1 =
+    Chart.Point(x,y,Name="desc1")    
+    |> Chart.WithDescription(description1)
+    |> Chart.Show
+
+(**
+
+![]({{root}}img/desc1.png)
+
+The `ChartDescription` type is a bit barebones for now, but you can contain any valid html in both `Heading` and `Text` fields:
+*)
+
+let description2 =
+    ChartDescription.create "<h1>I am heading</h1>" "<ol><li>Hi</li><li>there</li></ol>"
+
+(***do-not-eval***)
+let desc2 =
+    Chart.Point(x,y,Name="desc1")    
+    |> Chart.WithDescription(description2)
+    |> Chart.Show
+
+(**
+
+![]({{root}}img/desc2.png)
+
+## Adding additional head tags
+
+You can add any number of additional html tags to the documents `<head>` tag using `Chart.WithAdditionalHeadTags`.
+
+For example, you can load external css libraries to style the chart description:
+
+*)
+
+//html for description containing bulma classes such as "hero"
+let bulmaHero = """<section class="hero is-primary is-bold">
+  <div class="hero-body">
+    <p class="title">
+      Hero title
+    </p>
+    <p class="subtitle">
+      Hero subtitle
+    </p>
+  </div>
+</section>
+"""
+
+// chart description containing bulma classes
+let description3 =
+    ChartDescription.create 
+        """<h1 class="title">I am heading</h1>""" 
+       bulmaHero
+
+(***do-not-eval***)
+let desc3 =
+    Chart.Point(x,y,Name="desc3")    
+    |> Chart.WithDescription description3
+    // Add reference to the bulma css framework
+    |> Chart.WithAdditionalHeadTags ["""<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.2/css/bulma.min.css">"""]
+    |> Chart.Show
+
+(**
+
+![]({{root}}img/desc3.png)
+
+## Using MathTeX
+
+By popular request, `Chart.WithMathTex` is a prebuilt function to enable MathTeX for your generated plotly chart documents:
+
+*)
+
+[
+    Chart.Point([(1.,2.)],@"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$")
+    Chart.Point([(2.,4.)],@"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$")
+]
+|> Chart.Combine
+|> Chart.withTitle @"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$"
+// include mathtex tags in <head>. pass true to append these scripts, false to ONLY include MathTeX.
+|> Chart.WithMathTex(true)
+|> Chart.Show
+
+(**
+
+![]({{root}}img/desc4.png)
+
+*)

docs/2_0_line-scatter-plots.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Line and scatter plots
+category: Simple Charts
+categoryindex: 3
+index: 1
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (** 
 # Line and scatter plots
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=2_0_line-scatter-plots.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to create line and point charts in F#.
 

docs/2_1_bar-and-column-charts.fsx

@@ -1,3 +1,12 @@
+(**
+---
+title: Bar and column charts
+category: Simple Charts
+categoryindex: 3
+index: 2
+---
+*)
+
 (*** hide ***)
 
 (*** condition: prepare ***)
@@ -13,7 +22,9 @@
 (** 
 # Bar and column charts
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=2_1_bar-and-column-charts.ipynb)
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 *Summary:* This example shows how to create bar and a column charts in F#.