Skip to content

Commit

Permalink
Update docs for v5 (#458)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
kMutagene authored Jun 28, 2024
1 parent 98a4d18 commit d4c2ea8
Show file tree
Hide file tree
Showing 13 changed files with 321 additions and 13,855 deletions.
8 changes: 5 additions & 3 deletions .config/dotnet-tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}
}
6 changes: 2 additions & 4 deletions Plotly.NET.sln
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
25 changes: 25 additions & 0 deletions docs/_head.html
Original file line number Diff line number Diff line change
@@ -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/[email protected]/es5/tex-svg.js"></script>
103 changes: 0 additions & 103 deletions docs/_template.html

This file was deleted.

196 changes: 196 additions & 0 deletions docs/chart-layout/legends.fsx
Original file line number Diff line number Diff line change
@@ -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***)
Loading

0 comments on commit d4c2ea8

Please sign in to comment.