Skip to content

Commit c1b5f95

Browse files
kMutagenekMutagene
committed
improve readme
1 parent 2454c65 commit c1b5f95

5 files changed

Lines changed: 138 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -5,96 +5,150 @@
55
[![](https://img.shields.io/nuget/vpre/Plotly.NET)](https://www.nuget.org/packages/Plotly.NET/)
66
[![Discord](https://img.shields.io/discord/836161044501889064?color=purple&label=Join%20our%20Discord%21&logo=discord&logoColor=white)](https://discord.gg/k3kUtFY8DB)
77
![](https://img.shields.io/badge/supported%20plotly.js%20version-2.18.1-blue)
8-
9-
We have published a software paper on Plotly.NET. If you are using Plotly.NET for your research please cite or look at :
10-
118
[![DOI](https://img.shields.io/badge/DOI-10.12688%2Ff1000research.123971.1-brightgreen)](https://doi.org/10.12688/f1000research.123971.1)
129

13-
Plotly.NET provides functions for generating and rendering plotly.js charts in **.NET** programming languages 📈🚀.
14-
1510
### Table of contents
1611

12+
- [What is Plotly.NET?](#what-is-plotlynet)
1713
- [Installation](#installation)
18-
- [For applications and libraries](#for-applications-and-libraries)
19-
- [For scripting](#for-scripting)
20-
- [For dotnet interactive notebooks](#for-dotnet-interactive-notebooks)
21-
- [Nightly builds](#getting-nightly-builds)
2214
- [Documentation](#documentation)
23-
- [Getting started](#getting-started)
24-
- [Full library reference](#full-library-reference)
25-
- [Develop](#develop)
15+
- [Quick starts](#quick-starts)
16+
- [F#](#f)
17+
- [C#](#c)
18+
- [Samples and tutorials](#samples-and-tutorials)
19+
- [Full library reference](#full-library-reference)
20+
- [Development](#development)
2621
- [build](#build)
22+
- [running and writing tests](#running-and-writing-tests)
2723
- [docs](#docs)
28-
- [Contributors](#contributors)
29-
- [Library license](#library-license)
24+
- [Contributors](#contributors)
25+
- [Library license](#library-license)
26+
- [FAQ](#faq)
27+
28+
# What is Plotly.NET?
29+
30+
Plotly.NET is an Interactive charting library for **.NET** programming languages 📈🚀.
31+
32+
It is built on top of plotly.js and provides several API layers for creating, styling and rendering ✨**beatiful data visualizations**✨.
33+
34+
To get a deep-dive into the rationale behind the design choices of Plotly.NET, check out our [F1000Research paper](https://doi.org/10.12688/f1000research.123971.1)!
3035

36+
![](docs/img/showcase.gif)
37+
38+
In short, Plotly.NET consists of multiple API layers and packages:
39+
40+
- `Plotly.NET` - The core API is written in F# and provides multiple API layers to create and style charts - from the high-level, type-safe `Chart` API to low-level direct chart object manipulation. It is the foundation for all other packages.
41+
42+
- `Plotly.NET.Interactive` - This package provides interactive formatting extensions for .NET interactive notebooks.
43+
44+
- `Plotly.NET.ImageExport` - This package provides extensions for Plotly.NET to render charts as static images programmatically.
45+
46+
- `Plotly.NET.CSharp` - This package provides an idiomatic C# API. Note that you can use the core API in C#, this package just removes some friction at some places.
3147
# Installation
3248

33-
The most recent Plotly.NET package is [![](https://img.shields.io/nuget/vpre/Plotly.NET)](https://www.nuget.org/packages/Plotly.NET/).
49+
You can get all Plotly.NET packages via nuget:
3450

35-
Plotly.NET also provides several extension packages:
51+
| Package Name| Nuget |
52+
|---|---|
53+
| Plotly.NET | [![](https://img.shields.io/nuget/vpre/Plotly.NET)](https://www.nuget.org/packages/Plotly.NET/) |
54+
| Plotly.NET.Interactive | [![](https://img.shields.io/nuget/vpre/Plotly.NET.Interactive)](https://www.nuget.org/packages/Plotly.NET.Interactive/) |
55+
| Plotly.NET.ImageExport | [![](https://img.shields.io/nuget/vpre/Plotly.NET.ImageExport)](https://www.nuget.org/packages/Plotly.NET.ImageExport/) |
56+
| Plotly.NET.CSharp | [![](https://img.shields.io/nuget/vpre/Plotly.NET.CSharp)](https://www.nuget.org/packages/Plotly.NET.CSharp/) |
3657

37-
| Package Name| Plotly.NET.Interactive | Plotly.NET.ImageExport | Plotly.NET.CSharp |
38-
|---|---|---|---|
39-
| Description | Interactive formatting extension for .NET interactive notebooks| programmatic static image export | idiomatic C# API. Note that you can use the core API in C#, this package just removes some friction at some places. [See bindings progress](https://github.com/plotly/Plotly.NET/issues/296)|
40-
| Nuget | [![](https://img.shields.io/nuget/vpre/Plotly.NET.Interactive)](https://www.nuget.org/packages/Plotly.NET.Interactive/) | [![](https://img.shields.io/nuget/vpre/Plotly.NET.ImageExport)](https://www.nuget.org/packages/Plotly.NET.ImageExport/) | [![](https://img.shields.io/nuget/vpre/Plotly.NET.CSharp)](https://www.nuget.org/packages/Plotly.NET.CSharp/) |
58+
# Documentation
4159

42-
### For applications and libraries
60+
## Quick starts
4361

44-
- dotnet CLI
62+
### F#
4563

46-
```shell
47-
dotnet add package Plotly.NET <version>
48-
```
64+
In F# projects, just add the `Plotly.NET` package to your project and you are ready to go!
4965

50-
- paket CLI
66+
<details>
67+
<summary> 📖 Polyglot Notebook 📖 Quick start</summary>
5168

52-
```shell
53-
paket add Plotly.NET --version <version>
54-
```
69+
<br>
5570

56-
- package manager
71+
To enable Plotly.NET in a polyglot notebook, reference the `Plotly.NET.Interactive` package:
5772

58-
```shell
59-
Install-Package Plotly.NET -Version <version>
73+
```fsharp
74+
#r "nuget: Plotly.NET.Interactive"
6075
```
6176

62-
Or add the package reference directly to your `.*proj` file:
77+
To display a chart, just end a F# cell with it:
6378

79+
```fsharp
80+
open Plotly.NET
81+
82+
Chart.Point(
83+
x = [0 .. 10],
84+
y = [0 .. 10]
85+
)
86+
|> Chart.withTitle "Hello World!"
6487
```
65-
<PackageReference Include="Plotly.NET" Version="<version>" />
66-
```
88+
![notebook quichstart in F#](docs/img/notebook_quickstart_fsharp.png)
6789

6890

69-
### For scripting
91+
</details>
7092

71-
You can include the package via an inline package reference:
93+
<details>
94+
<summary> .fsx Scripting quickstart</summary>
7295

73-
```
74-
#r "nuget: Plotly.NET, <version>"
96+
To enable Plotly.NET in a .fsx script, reference the `Plotly.NET` package:
97+
98+
```fsharp
99+
#r "nuget: Plotly.NET"
75100
```
76101

77-
### For dotnet interactive notebooks
102+
To display a chart in your browser, use the `Chart.show` function:
78103

79-
You can use the same inline package reference as in script, but as an additional goodie,
80-
the interactive extensions for dotnet interactive have you covered for seamless chart rendering:
104+
```fsharp
105+
open Plotly.NET
81106
82-
```
83-
#r "nuget: Plotly.NET, <version>"
84-
#r "nuget: Plotly.NET.Interactive, <version>"
107+
Chart.Point(
108+
x = [0 .. 10],
109+
y = [0 .. 10]
110+
)
111+
|> Chart.withTitle "Hello World!"
112+
|> Chart.show
85113
```
86114

87115
</details>
88116

89-
# Documentation
117+
### C#
118+
119+
In C# projects, just add the `Plotly.NET.CSharp` package to your project and you are ready to go!
90120

91-
## Getting started
121+
<details>
122+
<summary> 📖 Polyglot Notebook 📖 Quick start</summary>
92123

93-
The landing page of our docs contains everything to get you started fast, check it out [📖 here](http://plotly.github.io/Plotly.NET/)
124+
<br>
125+
126+
To enable Plotly.NET in a polyglot notebook for C#, reference the `Plotly.NET.Interactive` and `Plotly.NET.CSharp` packages:
127+
128+
```csharp
129+
#r "nuget: Plotly.NET.Interactive"
130+
#r "nuget: Plotly.NET.CSharp"
131+
```
132+
133+
To display a chart, just end a C# cell with it:
134+
135+
```csharp
136+
using Plotly.NET.CSharp;
137+
138+
Chart.Point<int, int, string>(
139+
x: Enumerable.Range(0,11),
140+
y: Enumerable.Range(0,11)
141+
)
142+
```
143+
![notebook quichstart in C#](docs/img/notebook_quickstart_csharp.png)
144+
145+
## Samples and tutorials
146+
147+
You can find extensive documentation with samples and tutorials of the core `Plotly.NET` library [📖 here](http://plotly.github.io/Plotly.NET/).
94148

95149
## Full library reference
96150

97-
The API reference is available [📚 here](http://plotly.github.io/Plotly.NET/reference/index.html)
151+
The API reference for all packages is available [📚 here](http://plotly.github.io/Plotly.NET/reference/index.html)
98152

99153
The documentation for this library is automatically generated (using FSharp.Formatting) from *.fsx and *.md files in the docs folder. If you find a typo, please submit a pull request!
100154

@@ -112,7 +166,7 @@ Check the [build project](https://github.com/plotly/Plotly.NET/blob/dev/build) t
112166
# Build only
113167
./build.cmd
114168

115-
# Full release buildchain: build, test, pack, build the docs, push a git tag, publish thze nuget package, release the docs
169+
# Full release buildchain: build, test, pack, build the docs, push a git tag, publish the nuget package, release the docs
116170
./build.cmd release
117171

118172
# The same for prerelease versions:
@@ -132,6 +186,10 @@ build.sh prerelease
132186

133187
```
134188

189+
### running and writing tests
190+
191+
please refer to the detailed readme in the [tests folder](./tests/README.md)
192+
135193
### docs
136194

137195
The docs are contained in `.fsx` and `.md` files in the `docs` folder. To develop docs on a local server with hot reload, run the following in the root of the project:
@@ -155,3 +213,33 @@ Plotly.NET is a community maintained open source projects. Big thanks to all con
155213
## Library license
156214

157215
The library is available under the [MIT license](https://github.com/plotly/Plotly.NET/blob/dev/LICENSE).
216+
217+
# FAQ
218+
219+
<details>
220+
<summary>Why are there two separate packages for C# and F#?</summary>
221+
222+
<br>
223+
224+
These packages are not separate, Plotly.NET.CSharp is built **on top** of Plotly.NET.
225+
226+
`Plotly.NET` (written in F#) is the main project. It is designed with interoperability in mind, and it is possible to use it from C#.
227+
228+
Over the years, some friction between F# and C# have surfaced that cannot be overcome in the F# codebase. For more info, take a look at this issue where we discuss the topic: https://github.com/plotly/Plotly.NET/issues/285
229+
230+
The `Plotly.NET.CSharp` package (written in C#, using the F# API internally) is a thin wrapper around the core API. It is not necessary to use it, but it can make the API more idiomatic and ergonomic for C# users.
231+
</details>
232+
233+
<details>
234+
<summary>Can i use Plotly.NET in [insert your UI library here]?</summary>
235+
236+
<br>
237+
238+
It depends. Plotly.NET creates JSON for consumption by the plotly.js library. The actual rendering is done by plotly.js, in an environment where javascript can be run.
239+
240+
This means that your UI libs needs some way of displaying html and executing javascript to be compatible with Plotly.NET. That is true for most UI libs though, [here for example is a POC for Blazor]().
241+
242+
For Windows Forms and WPF you could use a WebView control to display the charts.
243+
244+
You could also use Plotly.NET.ImageExport in your backend to create static images of your charts and serve those in your UI.
245+
</details>

‎docs/img/notebook_quickstart_csharp.png‎

41.1 KB
Loading

‎docs/img/notebook_quickstart_fsharp.png‎

44 KB
Loading

‎docs/img/showcase.gif‎

620 KB
Loading

‎docs/img/showcase.png‎

828 KB
Loading

0 commit comments

Comments
 (0)