update docs: use named args only, use global plotly js reference, remove script download

Author: kMutagene

.config/dotnet-tools.json

@@ -3,13 +3,13 @@
   "isRoot": true,
   "tools": {
     "fantomas-tool": {
-      "version": "4.7.8",
+      "version": "4.7.9",
       "commands": [
         "fantomas"
       ]
     },
     "fsdocs-tool": {
-      "version": "15.0.1",
+      "version": "17.2.2",
       "commands": [
         "fsdocs"
       ]

build/BasicTasks.fs

@@ -30,7 +30,21 @@ let clean =
 
 /// builds the solution file (dotnet build solution.sln)
 let buildSolution =
-    BuildTask.create "BuildSolution" [ clean ] { solutionFile |> DotNet.build id }
+    BuildTask.create "BuildSolution" [ clean ] { 
+        solutionFile 
+        |> DotNet.build (fun p ->
+            let msBuildParams =
+                {p.MSBuildParams with 
+                    Properties = ([
+                        "warnon", "3390"
+                    ])
+                }
+            {
+                p with 
+                    MSBuildParams = msBuildParams
+            }
+        )
+    }
 
 /// builds the individual project files (dotnet build project.*proj)
 ///
@@ -50,6 +64,7 @@ let build = BuildTask.create "Build" [clean] {
                     Properties = ([
                         "AssemblyVersion", pInfo.AssemblyVersion
                         "InformationalVersion", pInfo.AssemblyInformationalVersion
+                        "warnon", "3390"
                     ])
                 }
             {

docs/00_0_basics.fsx

@@ -13,8 +13,11 @@ index: 1
 (*** condition: prepare ***)
 #r "nuget: Newtonsoft.JSON, 13.0.1"
 #r "nuget: DynamicObj, 2.0.0"
+#r "nuget: Giraffe.ViewEngine, 1.4.0"
 #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}}"
@@ -23,7 +26,6 @@ index: 1
 
 (**
 [![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb)&emsp;
-[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx)&emsp;
 [![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
 
 # Plotly.NET basics
@@ -53,7 +55,7 @@ These are mirrored in Plotly.NET's central type, `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:
 
-```fsharp
+```
 type GenericChart =
     | Chart of Trace * Layout * Config * DisplayOptions
     | MultiChart of Trace list * Layout * Config * DisplayOptions
@@ -76,13 +78,15 @@ Plotly.NET uses multiple layers of abstractions to generate valid plotly.js JSON
 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.
 
+In general, we recommend always using named arguments - even for mandatory arguments - as future changes/addition to the API might change the argument order.
+
 Here is an example on how to create a simple 2D point chart:
 *)
 
 open Plotly.NET
 
 let pointChart =
-    Chart.Point([1,2; 3,4])
+    Chart.Point(xy=[1,2; 3,4])
 
 (*** condition: ipynb ***)
 #if IPYNB

docs/00_1_image-export.fsx

@@ -13,7 +13,8 @@ index: 2
 (*** condition: prepare ***)
 #r "nuget: Newtonsoft.JSON, 13.0.1"
 #r "nuget: DynamicObj, 2.0.0"
-#r "nuget: PuppeteerSharp, 7.0.0"
+#r "nuget: Giraffe.ViewEngine, 1.4.0"
+#r "nuget: PuppeteerSharp, 9.0.2"
 #r "../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll"
 #r "../src/Plotly.NET.ImageExport/bin/Release/netstandard2.0/Plotly.NET.ImageExport.dll"
 
@@ -27,7 +28,6 @@ index: 2
 
 (**
 [![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)
 
 # Static image export
@@ -78,20 +78,6 @@ exampleChart
     Height=300
 )
 
-(*** condition: ipynb ***)
-#if IPYNB
-let imgString = $"""<img
-    src= "{exampleChart|> Chart.toBase64JPGString(Width=300,Height=300)}"
-/>"""
-DisplayExtensions.DisplayAs(imgString,"text/html")
-#endif // IPYNB
-
-(***hide***)
-$"""<img
-    src= "{exampleChart|> Chart.toBase64JPGString(Width=300,Height=300)}"
-/>"""
-(***include-it-raw***)
-
 (**
 ## Generating URIs for static chart images
 
@@ -105,6 +91,7 @@ By referencing the `Plotly.NET.ImageExport` package, you get access to:
 
 *)
 
+(***do-not-eval***)
 let base64JPG =
     exampleChart
     |> Chart.toBase64JPGString(
@@ -120,69 +107,4 @@ not even that is necessary and just the SVG string can be used.
 (***do-not-eval***)
 $"""<img
     src= "{base64JPG}"
-/>"""
-
-(*** condition: ipynb ***)
-#if IPYNB
-let imgString = $"""<img
-    src= "{base64JPG}"
-/>"""
-DisplayExtensions.DisplayAs(imgString,"text/html")
-#endif // IPYNB
-
-(***hide***)
-$"""<img
-    src= "{base64JPG}"
-/>"""
-
-(***include-it-raw***)
-
-(**
-SVGs can be included without the image tag:
-*)
-
-let svgString =
-    exampleChart
-    |> Chart.toSVGString(
-        Width=300,
-        Height=300
-    )
-
-svgString.Substring(0,300)
-|> printfn "%s"
-
-(***include-output***)
-
-(**
-In fact, the images shown on this site are included just the same way.
-
-## Including static images in dotnet interactive notebooks
-
-To include the images in dotnet interactive, convert them to html tags as above and include them via 
-dotnet interactive's `DisplayAs` function. The content type for PNG/JPG is "text/html", and "image/svg+xml" for SVG.
-*)
-
-let base64PNGTag =
-    let base64 =
-        exampleChart
-        |> Chart.toBase64PNGString(
-            Width=300,
-            Height=300
-        )
-    $"""<img src= "{base64JPG}"/>"""
-
-let svgString2 =
-    exampleChart
-    |> Chart.toSVGString(
-        Width=300,
-        Height=300
-    )
-
-// DisplayExtensions.DisplayAs(base64PNG,"text/html")
-// DisplayExtensions.DisplayAs(svgString2,"image/svg+xml")
-
-(*** condition: ipynb ***)
-#if IPYNB
-DisplayExtensions.DisplayAs(base64PNG,"text/html")
-DisplayExtensions.DisplayAs(svgString,"image/svg+xml")
-#endif // IPYNB
+/>"""