Skip to content

Commit 5b250f8

Browse files
kMutagenekMutagene
committed
add some small library specific readmes
1 parent d5c1ed4 commit 5b250f8

9 files changed

Lines changed: 202 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,10 @@ You can get all Plotly.NET packages via nuget:
5757

5858
| Package Name| Nuget |
5959
|---|---|
60-
| Plotly.NET | [![](https://img.shields.io/nuget/vpre/Plotly.NET)](https://www.nuget.org/packages/Plotly.NET/) |
61-
| Plotly.NET.Interactive | [![](https://img.shields.io/nuget/vpre/Plotly.NET.Interactive)](https://www.nuget.org/packages/Plotly.NET.Interactive/) |
62-
| Plotly.NET.ImageExport | [![](https://img.shields.io/nuget/vpre/Plotly.NET.ImageExport)](https://www.nuget.org/packages/Plotly.NET.ImageExport/) |
63-
| Plotly.NET.CSharp | [![](https://img.shields.io/nuget/vpre/Plotly.NET.CSharp)](https://www.nuget.org/packages/Plotly.NET.CSharp/) |
60+
| [Plotly.NET](src/Plotly.NET/README.md) | [![](https://img.shields.io/nuget/vpre/Plotly.NET)](https://www.nuget.org/packages/Plotly.NET/) |
61+
| [Plotly.NET.Interactive](src/Plotly.NET.Interactive/README.md) | [![](https://img.shields.io/nuget/vpre/Plotly.NET.Interactive)](https://www.nuget.org/packages/Plotly.NET.Interactive/) |
62+
| [Plotly.NET.ImageExport](src/Plotly.NET.ImageExport/README.md) | [![](https://img.shields.io/nuget/vpre/Plotly.NET.ImageExport)](https://www.nuget.org/packages/Plotly.NET.ImageExport/) |
63+
| [Plotly.NET.CSharp](src/Plotly.NET.CSharp/README.md) | [![](https://img.shields.io/nuget/vpre/Plotly.NET.CSharp)](https://www.nuget.org/packages/Plotly.NET.CSharp/) |
6464

6565
# Documentation
6666

‎src/Plotly.NET.CSharp/Plotly.NET.CSharp.csproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
<PackageLicenseExpression>MIT</PackageLicenseExpression>
2525
<PackageProjectUrl>https://plotly.net</PackageProjectUrl>
2626
<PackageIcon>logo.png</PackageIcon>
27+
<PackageReadmeFile>README.md</PackageReadmeFile>
2728
<PackageTags>visualization charting plotly fsharp csharp</PackageTags>
2829
<RepositoryUrl>https://github.com/plotly/Plotly.NET/</RepositoryUrl>
2930
<RepositoryType>git</RepositoryType>
@@ -32,6 +33,7 @@
3233
</PropertyGroup>
3334

3435
<ItemGroup>
36+
<None Update="README.md" Pack="true" PackagePath="\" />
3537
<None Include="..\..\docs\img\logo.png" Pack="true" PackagePath="\" />
3638
<ProjectReference Include="..\Plotly.NET\Plotly.NET.fsproj" PackageVersion="[6.0.0, 7.0.0)" />
3739
</ItemGroup>

‎src/Plotly.NET.CSharp/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Plotly.NET.CSharp
2+
3+
Create interactive charts in C# with chart constructors and fluent styling methods built on [Plotly.NET](https://plotly.net/). Charts render with plotly.js in a browser or a .NET Interactive notebook.
4+
5+
## Installation
6+
7+
Version 0.14.0 targets **.NET 10**. Your application must target .NET 10 or later. Installing this package also installs the core Plotly.NET library, with a supported version range of `>= 6.0.0` and `< 7.0.0`.
8+
9+
In a C# project:
10+
11+
```shell
12+
dotnet add package Plotly.NET.CSharp --version 0.14.0
13+
```
14+
15+
## Quick start
16+
17+
Put this code in `Program.cs` and run the application:
18+
19+
```csharp
20+
using Plotly.NET.CSharp;
21+
22+
var chart = Chart.Point<double, double, string>(
23+
x: new[] { 0.0, 1.0, 2.0, 3.0 },
24+
y: new[] { 1.0, 4.0, 9.0, 16.0 },
25+
Name: "Squares"
26+
);
27+
28+
chart.Show();
29+
```
30+
31+
`Show()` opens the chart in your browser. To save an HTML file instead, use `chart.SaveHtml("chart.html")`. The third generic argument, `string`, supplies the optional point-text type even when no text is provided.
32+
33+
For inline notebook output, reference [Plotly.NET.Interactive](https://www.nuget.org/packages/Plotly.NET.Interactive/6.0.0) as well and end the cell with the chart value. The notebook's C# kernel must support .NET 10.
34+
35+
## Documentation
36+
37+
- [Chart examples and guides](https://plotly.net/)
38+
- [API reference](https://plotly.net/reference/index.html)
39+
- [Encoded arrays and supported C# overloads](https://plotly.net/general/encoded-arrays.html)
40+
- [Release notes](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET.CSharp/RELEASE_NOTES.md)
41+
42+
Licensed under the [MIT License](https://github.com/plotly/Plotly.NET/blob/dev/LICENSE).

‎src/Plotly.NET.ImageExport/Plotly.NET.ImageExport.fsproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
<PackageLicenseExpression>MIT</PackageLicenseExpression>
1414
<PackageProjectUrl>https://plotly.net</PackageProjectUrl>
1515
<PackageIcon>logo.png</PackageIcon>
16+
<PackageReadmeFile>README.md</PackageReadmeFile>
1617
<PackageTags>visualization charting plotly fsharp csharp jpg png svg image</PackageTags>
1718
<RepositoryUrl>https://github.com/plotly/Plotly.NET/</RepositoryUrl>
1819
<RepositoryType>git</RepositoryType>
@@ -23,6 +24,7 @@
2324
<ItemGroup>
2425
<None Include="..\..\docs\img\logo.png" Pack="true" PackagePath="\" />
2526
<None Include="RELEASE_NOTES.md" />
27+
<None Include="README.md" Pack="true" PackagePath="\" />
2628
<Compile Include="AsyncHelper.fs" />
2729
<Compile Include="IGenericChartRenderer.fs" />
2830
<Compile Include="PuppeteerSharpRenderer.fs" />

‎src/Plotly.NET.ImageExport/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Plotly.NET.ImageExport
2+
3+
Render [Plotly.NET](https://plotly.net/) charts as PNG, JPEG, or SVG images using a headless browser powered by PuppeteerSharp.
4+
5+
## Install
6+
7+
```shell
8+
dotnet add package Plotly.NET.ImageExport --version 7.0.0
9+
```
10+
11+
Version 7 targets **.NET Standard 2.0** and depends on **Plotly.NET 6.x**, which NuGet installs automatically. Use a compatible .NET application runtime and an operating system that can run the browser described below.
12+
13+
## Export a chart
14+
15+
This F# script writes `chart.png` in the current directory:
16+
17+
```fsharp
18+
#r "nuget: Plotly.NET.ImageExport, 7.0.0"
19+
20+
open Plotly.NET
21+
open Plotly.NET.ImageExport
22+
23+
let chart =
24+
Chart.Line([ (1., 2.); (2., 4.); (3., 3.) ])
25+
|> Chart.withDisplayOptions(
26+
DisplayOptions.init(PlotlyJSReference = PlotlyJSReference.Full)
27+
)
28+
29+
chart |> Chart.savePNG("chart", Width = 800, Height = 450)
30+
```
31+
32+
Pass a path **without an extension**; the save functions append `.png`, `.jpg`, or `.svg`. The output directory must already exist and be writable. The example embeds plotly.js so the browser does not need to fetch it from a CDN.
33+
34+
## Output formats
35+
36+
| Format | Save to a file | Return an image string |
37+
| --- | --- | --- |
38+
| PNG | `Chart.savePNG` | `Chart.toBase64PNGString` — PNG data URI |
39+
| JPEG | `Chart.saveJPG` | `Chart.toBase64JPGString` — JPEG data URI |
40+
| SVG | `Chart.saveSVG` | `Chart.toSVGString` — SVG markup |
41+
42+
These functions accept `Width`, `Height`, and `Scale` options, defaulting to 600, 600, and 1.0. Corresponding `Async` functions, such as `Chart.savePNGAsync`, return tasks that you can await.
43+
44+
## Browser requirements
45+
46+
The default renderer uses PuppeteerSharp 24.40.0 to download a compatible Chrome browser when needed and launch it for each export. Browser setup requires network access and a writable browser download/cache location. The host must permit browser processes and provide the required operating-system libraries; see the [PuppeteerSharp prerequisites](https://github.com/hardkoded/puppeteer-sharp#prerequisites).
47+
48+
To use a preinstalled compatible Chrome/Chromium executable and skip the automatic download, set `PuppeteerSharpRendererOptions.localBrowserExecutablePath` to `Some "/absolute/path/to/chrome"` before exporting. Launch and navigation settings are available through `PuppeteerSharpRendererOptions.launchOptions` and `PuppeteerSharpRendererOptions.navigationOptions`.
49+
50+
Charts that reference external images, fonts, map resources, or a plotly.js CDN may still need network access during rendering.
51+
52+
See the [image export guide](https://plotly.net/general/image-export.html) for more examples and the [release notes](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET.ImageExport/RELEASE_NOTES.md) for version changes.
53+
54+
Licensed under the [MIT License](https://github.com/plotly/Plotly.NET/blob/dev/LICENSE).

‎src/Plotly.NET.Interactive/Plotly.NET.Interactive.fsproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
<PackageLicenseExpression>MIT</PackageLicenseExpression>
2323
<PackageProjectUrl>https://plotly.net</PackageProjectUrl>
2424
<PackageIcon>logo.png</PackageIcon>
25+
<PackageReadmeFile>README.md</PackageReadmeFile>
2526
<PackageTags>visualization charting plotly fsharp csharp</PackageTags>
2627
<RepositoryUrl>https://github.com/plotly/Plotly.NET/</RepositoryUrl>
2728
<RepositoryType>git</RepositoryType>
@@ -37,6 +38,7 @@
3738

3839
<ItemGroup>
3940
<None Include="RELEASE_NOTES.md" />
41+
<None Include="README.md" Pack="true" PackagePath="\" />
4042
<Compile Include="Formatters.fs" />
4143
<Compile Include="Extension.fs" />
4244
</ItemGroup>

‎src/Plotly.NET.Interactive/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Plotly.NET.Interactive
2+
3+
Display [Plotly.NET](https://plotly.net/) charts directly in .NET Interactive notebooks, including Polyglot Notebooks. This package registers an HTML formatter for chart values, so charts appear inline with zooming, panning, and hover information.
4+
5+
## Installation and quick start
6+
7+
Run this in an F# notebook cell:
8+
9+
```fsharp
10+
#r "nuget: Plotly.NET.Interactive, 6.0.0"
11+
```
12+
13+
Referencing the package loads the formatter automatically and installs the core Plotly.NET dependency. In the next F# cell, create a chart and leave it as the final expression:
14+
15+
```fsharp
16+
open Plotly.NET
17+
18+
Chart.Point(
19+
x = [ 0; 1; 2; 3 ],
20+
y = [ 1; 4; 9; 16 ]
21+
)
22+
|> Chart.withTitle "Squares"
23+
```
24+
25+
The notebook displays the chart below the cell. `Chart.show` opens a separate browser window; it is unnecessary for inline output. The formatter loads plotly.js from the Plotly CDN, so the notebook browser needs access to that CDN.
26+
27+
## Compatibility
28+
29+
Version 6.0.0 targets `netstandard2.1` and requires a compatible .NET Interactive host. It depends on Plotly.NET `>= 6.0.0` and `< 7.0.0`, and is built against `Microsoft.DotNet.Interactive` and `Microsoft.DotNet.Interactive.Formatting` version `1.0.0-beta.26120.1`. The package does not target .NET Framework.
30+
31+
For the C# chart API, also reference `Plotly.NET.CSharp` 0.14.0. That package requires a .NET 10 C# kernel. End a C# cell with the chart value to use the same formatter.
32+
33+
## Documentation
34+
35+
- [Installation and notebook examples](https://plotly.net/)
36+
- [Chart examples and guides](https://plotly.net/general/basics.html)
37+
- [API reference](https://plotly.net/reference/index.html)
38+
- [Release notes](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET.Interactive/RELEASE_NOTES.md)
39+
40+
Licensed under the [MIT License](https://github.com/plotly/Plotly.NET/blob/dev/LICENSE).

‎src/Plotly.NET/Plotly.NET.fsproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
<PackageLicenseExpression>MIT</PackageLicenseExpression>
2626
<PackageProjectUrl>https://plotly.net</PackageProjectUrl>
2727
<PackageIcon>logo.png</PackageIcon>
28+
<PackageReadmeFile>README.md</PackageReadmeFile>
2829
<PackageTags>visualization charting plotly fsharp csharp</PackageTags>
2930
<RepositoryUrl>https://github.com/plotly/Plotly.NET/</RepositoryUrl>
3031
<RepositoryType>git</RepositoryType>
@@ -43,6 +44,7 @@
4344
</ItemGroup>
4445
<ItemGroup>
4546
<None Include="RELEASE_NOTES.md" />
47+
<None Include="README.md" Pack="true" PackagePath="\" />
4648
<None Include="..\..\docs\img\logo.png" Pack="true" PackagePath="\" />
4749
<EmbeddedResource Include="plotly-2.28.0.min.js" />
4850
<EmbeddedResource Include="plotly-2.28.0.min.js.LICENSE.txt" />

‎src/Plotly.NET/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Plotly.NET
2+
3+
Create interactive plotly.js charts in .NET. Plotly.NET provides an F# API for building,
4+
styling, combining, and rendering charts, with lower-level access to traces, layouts,
5+
and configuration. This is the core library used by the other Plotly.NET packages.
6+
7+
## Installation
8+
9+
```shell
10+
dotnet add package Plotly.NET --version 6.0.0
11+
```
12+
13+
The library targets .NET Standard 2.0. For an idiomatic C# API, install
14+
[Plotly.NET.CSharp](https://www.nuget.org/packages/Plotly.NET.CSharp/) as well.
15+
16+
## Quick start
17+
18+
In an F# project with the package installed:
19+
20+
```fsharp
21+
open Plotly.NET
22+
23+
let chart =
24+
Chart.Line(
25+
x = [ 1; 2; 3; 4 ],
26+
y = [ 2; 5; 3; 8 ]
27+
)
28+
|> Chart.withTitle "My first chart"
29+
30+
chart |> Chart.saveHtml "chart.html"
31+
```
32+
33+
Open `chart.html` in a browser to interact with the chart. Use `chart |> Chart.show`
34+
to save a temporary HTML file and open it in your default browser automatically.
35+
For an `.fsx` script, add `#r "nuget: Plotly.NET, 6.0.0"` before the example.
36+
37+
By default, the HTML loads plotly.js from a CDN and needs an internet connection.
38+
See [display options](https://plotly.net/general/display-options.html) for using an
39+
embedded or local plotly.js reference.
40+
41+
## Related packages
42+
43+
- [Plotly.NET.CSharp](https://www.nuget.org/packages/Plotly.NET.CSharp/): C# chart factories and extension methods.
44+
- [Plotly.NET.Interactive](https://www.nuget.org/packages/Plotly.NET.Interactive/): inline chart display in .NET Interactive / Polyglot Notebooks.
45+
- [Plotly.NET.ImageExport](https://www.nuget.org/packages/Plotly.NET.ImageExport/): programmatic static image export.
46+
47+
## Documentation and support
48+
49+
- [Examples and tutorials](https://plotly.net/)
50+
- [API reference](https://plotly.net/reference/index.html)
51+
- [Release notes and migration information](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET/RELEASE_NOTES.md)
52+
- [Source code and issue tracker](https://github.com/plotly/Plotly.NET)
53+
54+
Plotly.NET is licensed under the [MIT license](https://github.com/plotly/Plotly.NET/blob/dev/LICENSE).

0 commit comments

Comments
 (0)