Skip to content

Commit e932c17

Browse files
archmojarchmoj
authored
Merge pull request #5705 from plotly/readme-order
Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README
2 parents e720965 + d6b5498 commit e932c17

File tree

6 files changed

+252
-460
lines changed

6 files changed

+252
-460
lines changed

Diff for: ‎BUILDING.md

+6-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Alternative ways to require or build plotly.js
2-
Depending on your needs, to bundle plotly.js into your application one of [the browserified distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) on npm could be used.
2+
Depending on your needs you may require/import one of [the distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) or [a plotly.js/lib index file](https://github.com/plotly/plotly.js/tree/master/lib) and integrate it into your application.
3+
4+
The sections below provide additional info in respect to alternative building frameworks.
35

46
## Browserify example
57

@@ -16,10 +18,7 @@ then simply run
1618
browserify index.js > bundle.js
1719
```
1820

19-
20-
21-
The sections below provide additional info in respect to alternative building frameworks.
22-
21+
---
2322
## Webpack
2423

2524
For plotly.js to build with Webpack you will need to install [[email protected]+](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json`. This adds Browserify transform compatibility to Webpack which is necessary for some plotly.js dependencies.
@@ -39,6 +38,7 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here]
3938
...
4039
```
4140

41+
---
4242
## Angular CLI
4343

4444
Since Angular uses webpack under the hood and doesn't allow easily to change it's webpack configuration, there is some work needed using a `custom-webpack` builder to get things going.
@@ -99,3 +99,4 @@ module.exports = {
9999

100100
It's important to set `projects.x.architect.build.builder` and `projects.x.architect.build.options.customWebpackConfig`.
101101
If you have more projects in your `angular.json` make sure to adjust their settings accordingly.
102+
---

Diff for: ‎CUSTOM_BUNDLE.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Custom bundle
2+
You can simply make custom bundles yourself, if none of the [distributed packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) meet your needs, or you want to make a more optimized bundle file with/without specific traces and transforms.
3+
4+
Install plotly.js, move to plotly.js folder then install plotly.js dependencies:
5+
```sh
6+
npm i [email protected]
7+
cd node_modules/plotly.js
8+
npm i
9+
```
10+
11+
By default all traces and transforms are included in the bundle if you simply run:
12+
```sh
13+
npm run partial-bundle
14+
```
15+
16+
Use the `traces` option to include just the trace types you need.
17+
```sh
18+
npm run partial-bundle -- --traces scatter,scattergl,scatter3d
19+
```
20+
Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
21+
[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.
22+
23+
Use the `transforms` option to specify which should be included.
24+
```sh
25+
npm run partial-bundle -- --transforms sort,filter
26+
```
27+
28+
Or use `transforms none` to exclude them all.
29+
```sh
30+
npm run partial-bundle -- --transforms none
31+
```
32+
33+
Use the `out` option to change the bundle filename (default `custom`).
34+
The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
35+
```sh
36+
npm run partial-bundle -- --out myBundleName
37+
```
38+
39+
Use the `unminified` option to disable compression.
40+
```sh
41+
npm run partial-bundle -- --unminified
42+
```
43+
44+
# Example illustrating use of different options together
45+
To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
46+
```sh
47+
npm run partial-bundle -- \
48+
--unminified \
49+
--out myScatters \
50+
--traces scatter,scattergl,scatter3d \
51+
--transforms none
52+
```
53+
Or simply on one line:
54+
```sh
55+
npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
56+
```

Diff for: ‎README.md

+67-100
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,19 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu
1818

1919
## Table of contents
2020

21-
* [Quick start options](#quick-start-options)
22-
* [Partial bundles](#partial-bundles)
21+
* [Load from npm (Node.js Package Manager)](#load-from-npm-nodejs-package-manager)
22+
* [Load from Content Delivery Network (CDN)](#load-from-content-delivery-network-cdn)
23+
* [Bundles](#bundles)
2324
* [Alternative ways to require or build plotly.js](#alternative-ways-to-require-or-build-plotlyjs)
24-
* [Bugs and feature requests](#bugs-and-feature-requests)
2525
* [Documentation](#documentation)
26+
* [Bugs and feature requests](#bugs-and-feature-requests)
2627
* [Contributing](#contributing)
27-
* [Community](#community)
28-
* [Versioning](#versioning)
29-
* [Notable contributors](#creators)
28+
* [Notable contributors](#notable-contributors)
3029
* [Copyright and license](#copyright-and-license)
30+
* [Community](#community)
3131

3232
---
33-
## Quick start options
34-
35-
### Install with npm
33+
## Load from npm (Node.js Package Manager)
3634

3735
```sh
3836
npm install plotly.js-dist-min
@@ -42,95 +40,66 @@ and import plotly.js as
4240

4341
```js
4442
import Plotly from 'plotly.js-dist-min'
45-
// Or using require,
43+
```
44+
Or
45+
```js
4646
var Plotly = require('plotly.js-dist-min')
4747
```
4848

49-
### Use the plotly.js CDN hosted by Fastly
49+
---
50+
## Load from Content Delivery Network (CDN)
51+
Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>.
5052

51-
#### A minified plotly.js X.Y.Z release
53+
### Usage example
5254
```html
53-
<script src="https://cdn.plot.ly/plotly-1.58.4.min.js" charset="utf-8"></script>
55+
<head>
56+
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
57+
</head>
58+
<body>
59+
<div id="gd"></div>
60+
61+
<script>
62+
Plotly.newPlot("gd", {
63+
"data": [{
64+
"y": [1, 2, 3]
65+
}],
66+
"layout": {
67+
"width": 600,
68+
"height": 400
69+
}
70+
});
71+
</script>
72+
</body>
5473
```
74+
In the example above `Plotly` object is added to the window scope by the script in the `head` section.
75+
The `newPlot` method is then used to draw an interactive figure as described by `data` and `layout` into the desired `div` here named `gd`.
76+
As demonstrated in the example above basic knowledge of `html` and [JSON](https://en.wikipedia.org/wiki/JSON) syntax is enough to get started i.e. with/without JavaScript!
77+
To learn and build more with plotly.js please visit [plotly.js documentation](https://plotly.com/javascript).
5578

56-
#### An un-minified version is also available
79+
### Un-minified versions are also available on CDN
80+
While non-minified source files may contain characters outside UTF-8, it is recommended that you specify the `charset` when loading those bundles.
5781
```html
58-
<script src="https://cdn.plot.ly/plotly-1.58.4.js" charset="utf-8"></script>
59-
```
60-
61-
and use the `Plotly` object in the window scope.
62-
63-
##### Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
64-
65-
Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>
66-
67-
### Download the latest release or a release candidate (rc)
68-
69-
[Latest and rc releases on GitHub](https://github.com/plotly/plotly.js/releases/)
70-
71-
and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
72-
73-
#### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples.
74-
75-
---
76-
## Partial bundles
77-
78-
There are two kinds of plotly.js partial bundles:
79-
1. The official partial bundles that are distributed to `npm` and the CDN, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
80-
2. Custom bundles you can create yourself, if none of the distributed packages meet your needs.
81-
82-
Use the `traces` option to include just the trace types you need.
83-
```sh
84-
npm run partial-bundle -- --traces scatter,scattergl,scatter3d
85-
```
86-
Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
87-
[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.
88-
89-
By default all transforms are included in the bundle.
90-
Use the `transforms` option to specify which should be included.
91-
```sh
92-
npm run partial-bundle -- --transforms sort,filter
82+
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.js" charset="utf-8"></script>
9383
```
9484

95-
Or use `transforms none` to exclude them all.
96-
```sh
97-
npm run partial-bundle -- --transforms none
98-
```
99-
100-
Use the `out` option to change the bundle filename (default `custom`).
101-
The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
102-
```sh
103-
npm run partial-bundle -- --out myBundleName
104-
```
85+
> Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
10586
106-
Use the `unminified` option to disable compression.
107-
```sh
108-
npm run partial-bundle -- --unminified
87+
### To support MathJax
88+
Load relevant MathJax (v2) files *Before* the plotly.js script tag:
89+
```html
90+
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
91+
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
10992
```
11093

111-
### Example illustrating use of different options together
112-
To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
113-
```sh
114-
npm run partial-bundle -- \
115-
--unminified \
116-
--out myScatters \
117-
--traces scatter,scattergl,scatter3d \
118-
--transforms none
119-
```
120-
Or simply on one line:
121-
```sh
122-
npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
123-
```
94+
## Bundles
95+
There are two kinds of plotly.js bundles:
96+
1. Complete and partial official bundles that are distributed to `npm` and the `CDN`, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
97+
2. Custom bundles you can create yourself to optimize the size of bundle depending on your needs. Please visit [CUSTOM_BUNDLE](https://github.com/plotly/plotly.js/blob/master/CUSTOM_BUNDLE.md) for more information.
12498

12599
---
126100
## Alternative ways to require or build plotly.js
127101
If your library needs to bundle or directly require [plotly.js/lib/index.js](https://github.com/plotly/plotly.js/blob/master/lib/index.js) or parts of its modules similar to [index-basic](https://github.com/plotly/plotly.js/blob/master/lib/index-basic.js) in some other way than via an official or a custom bundle, or in case you want to tweak the default build configurations of `browserify` or `webpack`, etc. then please visit [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md).
128102

129-
---
130-
## Bugs and feature requests
131-
132-
Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md)
133-
134103
---
135104
## Documentation
136105

@@ -139,32 +108,16 @@ Official plotly.js documentation is hosted at [https://plotly.com/javascript](ht
139108
These pages are generated by the Plotly [graphing-library-docs repo](https://github.com/plotly/graphing-library-docs) built with [Jekyll](https://jekyllrb.com/) and publicly hosted on GitHub Pages.
140109
For more info about contributing to Plotly documentation, please read through [contributing guidelines](https://github.com/plotly/graphing-library-docs/blob/master/README.md).
141110

142-
### To support MathJax
143-
Load relevant MathJax (v2) files *Before* the plotly.js script tag:
144-
```html
145-
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
146-
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
147-
```
148-
149111
---
150-
## Contributing
151-
152-
Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development.
112+
## Bugs and feature requests
153113

154-
---
155-
## Community
114+
Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md)
156115

157-
* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
158-
* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
159-
on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
160-
* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly).
161116

162117
---
163-
## Versioning
164-
165-
This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).
118+
## Contributing
166119

167-
See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
120+
Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development.
168121

169122
---
170123
## Notable contributors
@@ -197,3 +150,17 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
197150
Code and documentation copyright 2021 Plotly, Inc.
198151

199152
Code released under the [MIT license](https://github.com/plotly/plotly.js/blob/master/LICENSE).
153+
154+
### Versioning
155+
156+
This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).
157+
158+
See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
159+
160+
---
161+
## Community
162+
163+
* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
164+
* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
165+
on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
166+
* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly).

0 commit comments

Comments
 (0)