Update docs for v5 (#458)

* use fsdocs 20.0.1

* add docs for legends

* add temporary fix for multi legend regression bug in docs

* finish update existing docs to 5.0.0

* Add subplot title docs

* add docs minimal theme customization

.config/dotnet-tools.json

@@ -6,13 +6,15 @@
  "version": "5.2.2",
  "commands": [
  "fantomas"
- ]
+ ],
+ "rollForward": false
  },
  "fsdocs-tool": {
- "version": "19.1.1",
+ "version": "20.0.1",
  "commands": [
  "fsdocs"
- ]
+ ],
+ "rollForward": false
  }
  }
 }

Plotly.NET.sln

@@ -42,14 +42,11 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7B09CC0A-F
  docs\Dockerfile = docs\Dockerfile
  docs\index.fsx = docs\index.fsx
  docs\NuGet.config = docs\NuGet.config
- docs\_template.html = docs\_template.html
+ docs\_head.html = docs\_head.html
  docs\_template.ipynb = docs\_template.ipynb
  EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "reference", "reference", "{5219BAC7-ACE6-435F-A983-BC63DD7B745E}"
- ProjectSection(SolutionItems) = preProject
- docs\reference\_template.html = docs\reference\_template.html
- EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{60FB82C0-F472-494E-BCF7-7B3C54212406}"
  ProjectSection(SolutionItems) = preProject
@@ -153,6 +150,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "01_chart-layout", "01_chart
  docs\chart-layout\axis-styling.fsx = docs\chart-layout\axis-styling.fsx
  docs\chart-layout\errorbars.fsx = docs\chart-layout\errorbars.fsx
  docs\chart-layout\layout_images.fsx = docs\chart-layout\layout_images.fsx
+ docs\chart-layout\legends.fsx = docs\chart-layout\legends.fsx
  docs\chart-layout\multiple-charts.fsx = docs\chart-layout\multiple-charts.fsx
  docs\chart-layout\shapes.fsx = docs\chart-layout\shapes.fsx
  docs\chart-layout\sliders.fsx = docs\chart-layout\sliders.fsx

docs/_head.html

@@ -0,0 +1,25 @@
+<meta charset="utf-8">
+<title>{{fsdocs-page-title}}</title>
+<meta name="author" content="{{fsdocs-authors}}">
+<meta name="description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+
+<!-- Opengraph properties (https://ogp.me/) -->
+<meta property="og:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}" />
+<meta property="og:url" content="{{root}}{{fsdocs-source-basename}}.html">
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content="Plotly.NET" />
+<meta property="og:description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+<meta property="og:image" content="{{root}}img/logo_meta_tags.png">
+
+<!-- Twitter cards -->
+<meta name="twitter:card" content="summary_large_image">
+<meta property="twitter:domain" content="{{root}}{{fsdocs-source-basename}}.html">
+<meta property="twitter:url" content="https://plotly.net">
+<meta name="twitter:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}">
+<meta name="twitter:description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+<meta name="twitter:image" content="{{root}}img/logo_meta_tags.png">
+
+<link rel="shortcut icon" type="image/x-icon" href="{{root}}/img/favicon.ico">
+<script src="https://cdn.plot.ly/plotly-2.27.1.min.js"></script>
+<script>MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] } };</script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@3.2.0/es5/tex-svg.js"></script>

docs/chart-layout/legends.fsx

@@ -0,0 +1,196 @@
+(**
+---
+title: Legends
+category: Chart Layout
+categoryindex: 2
+index: 9
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 13.0.1"
+#r "nuget: DynamicObj, 2.0.0"
+#r "nuget: Giraffe.ViewEngine.StrongName, 2.0.0-alpha1"
+#r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll"
+
+Plotly.NET.Defaults.DefaultDisplayOptions <-
+ Plotly.NET.DisplayOptions.init (PlotlyJSReference = Plotly.NET.PlotlyJSReference.NoReference)
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Legends
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/plotly.net/gh-pages?urlpath=/tree/home/jovyan/{{fsdocs-source-basename}}.ipynb)&emsp;
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+*Summary:* This example shows how to create Legends and add them to the Charts in F#.
+
+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. ]
+
+// note that legends are not shown on charts with only one trace, 
+// which is why we need to set the trace to visible manually on this chart
+let simple_chart = Chart.Point(x, y, ShowLegend = true, Name = "test_chart")
+
+(**
+## Creating a legend
+
+Legends are `LayoutObjects` that can be added to a chart's `Layout`. The `LayoutLegend.init` function is used to create a legend object, which can then be added to a chart using the `Chart.withLegend` function:
+*)
+open Plotly.NET.LayoutObjects
+
+let my_legend =
+ Legend.init (
+ Title = Title.init("my first legend!"),
+ BorderColor = Color.fromString "black",
+ BorderWidth = 1
+ )
+
+let first_legend_chart =
+ simple_chart
+ |> Chart.withLegend my_legend
+
+(*** condition: ipynb ***)
+#if IPYNB
+first_legend_chart
+#endif // IPYNB
+
+(***hide***)
+first_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Styling existing legends
+
+The `Chart.withLegendStyle` function can be used to update the style of an existing legend. 
+The following code will move the existing legend to the center bottom of the chart:
+*)
+
+let styled_legend_chart =
+ first_legend_chart
+ |> Chart.withLegendStyle(
+ Orientation = StyleParam.Orientation.Horizontal,
+ X = 0.5,
+ XAnchor = StyleParam.XAnchorPosition.Center
+ )
+
+(*** condition: ipynb ***)
+#if IPYNB
+styled_legend_chart
+#endif // IPYNB
+
+(***hide***)
+styled_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Grouping legend items
+
+You can group multiple traces as a single legend item by setting the `LegendGroup` property of the individual traces to the same value:
+*)
+
+let grouped_legend_chart =
+ [
+ Chart.Point(x, y)
+ |> GenericChart.mapTrace (
+ Trace2DStyle.Scatter(
+ LegendGroup = "Group A",
+ LegendGroupTitle = (Title.init (Text = "Group A"))
+ )
+ )
+ Chart.Point(y, x)
+ |> GenericChart.mapTrace (
+ Trace2DStyle.Scatter(
+ LegendGroup = "Group A"
+ )
+ )
+ Chart.Point(y, y)
+ |> GenericChart.mapTrace (
+ Trace2DStyle.Scatter(
+ LegendGroup = "Group B",
+ LegendGroupTitle = (Title.init (Text = "Group B"))
+ )
+ )
+ ]
+ |> Chart.combine
+
+(*** condition: ipynb ***)
+#if IPYNB
+grouped_legend_chart
+#endif // IPYNB
+
+(***hide***)
+grouped_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Multiple legends
+
+Starting with Plotly.NET 5.0.0, the multiple legends feature from plotl.js v2.22+ is supported.
+
+However, plotly.js has a [regression bug starting from 2.24.3](https://github.com/plotly/plotly.js/issues/7023), which causes multiple legends to not display correctly
+
+This means that the referenced plotly.js version has to be changed to <2.24.3 to use this feature. Note that features introduced in plotly.js/.NET after this version will not work on a chart using that reference.
+Future versions of plotly.js will hopefully fix this issue.
+
+Similarily to how multiple axes are handled, multiple legends are added by providing an additional `Id` argument when using the `Chart.withLegend` function:
+
+To select which legend a trace should belong to, use `Chart.withLegendAnchor` with the corresponding `id` argument.
+*)
+
+
+let multi_legend_chart =
+ [
+ Chart.Point(x, y)
+ |> Chart.withLegendAnchor 1
+ Chart.Point(y, x)
+ |> Chart.withLegendAnchor 2
+ ]
+ |> Chart.combine
+ |> Chart.withLegend(
+ Legend.init(
+ BorderColor = Color.fromKeyword Blue,
+ BorderWidth = 2,
+ Title = Title.init(
+ Text = "Legend 1"
+ )
+ )
+ )
+ |> Chart.withLegend(
+ Legend.init(
+ X = 0.75,
+ Y = 0.75,
+ BorderColor = Color.fromKeyword Red,
+ BorderWidth = 2,
+ Title = Title.init(
+ Text = "Legend 2"
+ )
+ ),
+ Id = 2
+ )
+ // set lower plotly.js version to avoid regression bug
+ |> Chart.withDisplayOptionsStyle(
+ PlotlyJSReference = Plotly.NET.PlotlyJSReference.CDN "https://cdn.plot.ly/plotly-2.23.0.min.js"
+ )
+
+(*** condition: ipynb ***)
+#if IPYNB
+multi_legend_chart
+#endif // IPYNB
+
+(***hide***)
+multi_legend_chart |> GenericChart.toEmbeddedHTML
+(***include-it-raw***)