8000 Merge pull request #5704 from plotly/building-readme · plotly/plotly.js@e720965 · GitHub
[go: up one dir, main page]
Skip to content

Commit e720965

Browse files
archmojarchmoj
authored
Merge pull request #5704 from plotly/building-readme
Revise building readme
2 parents e50b063 + 4d662af commit e720965

File tree

2 files changed

+55
-38
lines changed

2 files changed

+55
-38
lines changed

‎BUILDING.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,24 @@
1-
# Building plotly.js
1+
# 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.
23

3-
The easiest way to bundle plotly.js into your application is to use one of the distributed plotly.js packages on npm. These distributed packages should just work with **any** build framework. That said, if you're looking to save a few bytes, read the section below corresponding to your building framework.
4+
## Browserify example
5+
6+
Given source file:
7+
```js
8+
// file: index.js
9+
var Plotly = require('plotly.js-dist-min');
10+
// ....
11+
```
12+
13+
then simply run
14+
15+
```sh
16+
browserify index.js > bundle.js
17+
```
18+
19+
20+
21+
The sections below provide additional info in respect to alternative building frameworks.
422

523
## Webpack
624

@@ -21,24 +39,6 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here]
2139
...
2240
```
2341

24-
## Browserify
25-
26-
Given source file:
27-
28-
```js
29-
// file: index.js
30-
31-
var Plotly = require('plotly.js');
32-
33-
// ....
34-
```
35-
36-
then simply run,
37-
38-
```
39-
browserify index.js > bundle.js
40-
```
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.

‎README.md

Lines changed: 35 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -19,29 +19,31 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu
1919
## Table of contents
2020

2121
* [Quick start options](#quick-start-options)
22-
* [Modules](#modules)
23-
* [Building plotly.js](#building-plotlyjs)
22+
* [Partial bundles](#partial-bundles)
23+
* [Alternative ways to require or build plotly.js](#alternative-ways-to-require-or-build-plotlyjs)
2424
* [Bugs and feature requests](#bugs-and-feature-requests)
2525
* [Documentation](#documentation)
2626
* [Contributing](#contributing)
2727
* [Community](#community)
28-
* [Notable Contributors](#creators)
28+
* [Versioning](#versioning)
29+
* [Notable contributors](#creators)
2930
* [Copyright and license](#copyright-and-license)
3031

32+
---
3133
## Quick start options
3234

3335
### Install with npm
3436

3537
```sh
36-
npm install plotly.js-dist
38+
npm install plotly.js-dist-min
3739
```
3840

3941
and import plotly.js as
4042

4143
```js
42-
import Plotly from 'plotly.js-dist'
44+
import Plotly from 'plotly.js-dist-min'
4345
// Or using require,
44-
var Plotly = require('plotly.js-dist')
46+
var Plotly = require('plotly.js-dist-min')
4547
```
4648

4749
### Use the plotly.js CDN hosted by Fastly
@@ -70,88 +72,102 @@ and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly
7072

7173
#### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples.
7274

75+
---
7376
## Partial bundles
7477

7578
There are two kinds of plotly.js partial bundles:
7679
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).
7780
2. Custom bundles you can create yourself, if none of the distributed packages meet your needs.
7881

7982
Use the `traces` option to include just the trace types you need.
80-
```
83+
```sh
8184
npm run partial-bundle -- --traces scatter,scattergl,scatter3d
8285
```
8386
Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
8487
[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.
8588

8689
By default all transforms are included in the bundle.
8790
Use the `transforms` option to specify which should be included.
88-
```
91+
```sh
8992
npm run partial-bundle -- --transforms sort,filter
9093
```
9194

9295
Or use `transforms none` to exclude them all.
93-
```
96+
```sh
9497
npm run partial-bundle -- --transforms none
9598
```
9699

97100
Use the `out` option to change the bundle filename (default `custom`).
98101
The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
99-
```
102+
```sh
100103
npm run partial-bundle -- --out myBundleName
101104
```
102105

103106
Use the `unminified` option to disable compression.
104-
```
107+
```sh
105108
npm run partial-bundle -- --unminified
106109
```
107110

108111
### Example illustrating use of different options together
109112
To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
110-
```
113+
```sh
111114
npm run partial-bundle -- \
112115
--unminified \
113116
--out myScatters \
114117
--traces scatter,scattergl,scatter3d \
115118
--transforms none
116119
```
117120
Or simply on one line:
118-
```
121+
```sh
119122
npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
120123
```
121124

122-
## Building plotly.js
123-
124-
Building instructions using `webpack`, `browserify` and other build frameworks are in [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md)
125+
---
126+
## Alternative ways to require or build plotly.js
127+
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).
125128

129+
---
126130
## Bugs and feature requests
127131

128132
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)
129133

134+
---
130135
## Documentation
131136

132137
Official plotly.js documentation is hosted at [https://plotly.com/javascript](https://plotly.com/javascript).
133138

134139
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.
135140
For more info about contributing to Plotly documentation, please read through [contributing guidelines](https://github.com/plotly/graphing-library-docs/blob/master/README.md).
136141

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+
149+
---
137150
## Contributing
138151

139152
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.
140153

154+
---
141155
## Community
142156

143157
* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
144158
* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
145159
on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
146160
* 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).
147161

162+
---
148163
## Versioning
149164

150165
This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).
151166

152167
See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
153168

154-
## Notable Contributors
169+
---
170+
## Notable contributors
155171

156172
Plotly.js is at the core of a large and dynamic ecosystem with many contributors who file issues, reproduce bugs, suggest improvements, write code in this repo (and other upstream or downstream ones) and help users in the Plotly community forum. The following people deserve special recognition for their outsized contributions to this ecosystem:
157173

@@ -160,7 +176,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
160176
|**Alex C. Johnson**| [@alexcjohnson](https://github.com/alexcjohnson) | | Active, Maintainer |
161177
|**Mojtaba Samimi** | [@archmoj](https://github.com/archmoj) | [@solarchvision](https://twitter.com/solarchvision) | Active, Maintainer |
162178
|**Antoine Roy-Gobeil** | [@antoinerg](https://github.com/antoinerg) | | Active, Maintainer |
163-
|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active |
179+
|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active, Maintainer |
164180
|**Jon Mease** | [@jonmmease](https://github.com/jonmmease) | [@jonmmease](https://twitter.com/jonmmease) | Active |
165181
|**Étienne Tétreault-Pinard**| [@etpinard](https://github.com/etpinard) | [@etpinard](https://twitter.com/etpinard) | Hall of Fame |
166182
|**Mikola Lysenko**| [@mikolalysenko](https://github.com/mikolalysenko) | [@MikolaLysenko](https://twitter.com/MikolaLysenko) | Hall of Fame |
@@ -175,6 +191,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
175191
|**Chris Parmer**| [@chriddyp](https://github.com/chriddyp) | | Hall of Fame |
176192
|**Alex Vados**| [@alexander-daniel](https://github.com/alexander-daniel) | | Hall of Fame |
177193

194+
---
178195
## Copyright and license
179196

180197
Code and documentation copyright 2021 Plotly, Inc.

0 commit comments

Comments
 (0)
0