|
169 | 169 | [`pip`](https://pip.pypa.io/en/stable/reference/pip_install/#install-editable) |
170 | 170 | documentation on _development mode_. |
171 | 171 |
|
| 172 | +### Updating the `js/` directory |
| 173 | +**This is only necessary if you're making changes to the `js/` directory.** |
| 174 | +To rebuild the javascript, you can run `npm install && npm run build` from the `js/` directory. |
| 175 | + |
| 176 | +**Notes on the contents of the `js/` directory:** |
| 177 | +The `js/` directory contains code to run plotly in Jupyter notebooks. It is shipped |
| 178 | +as part of the python package, so the build files are located in the `plotly/` directory |
| 179 | +under `plotly/labextension`. The files in that directory are committed so that if you |
| 180 | +aren't making a change to the `js/` directory, you don't have to worry about building it. |
| 181 | +There are two kinds of Jupyter support included in the `js/` directory: |
| 182 | +1. **Widget**: This is a more interactive model for rendering plotly in notebooks. You can use this |
| 183 | +through `FigureWidget`. It allows for communication between the javascript frontend and the python backend, |
| 184 | +but it has the drawback of requiring an additional package (`anywidget`). The code for this is located under |
| 185 | +`js/src/widget.ts`, and is included in the python package through `plotly/package_data/widgetbundle.js`. |
| 186 | +2. **Mime Renderer**: This is a less interactive model. The plot is rendered but can't send any |
| 187 | +information back to the python side. For most people this is enough, so this is the default |
| 188 | +renderer for the `Figure` class. The mime renderer is used automatically by JupyterLab / Jupyter Notebook |
| 189 | +when it sees the mimetype `application/vnd.plotly.v1+json` in the notebook output. We include a JupyterLab extension in our python package that loads `plotly.js` and renders it when that mimetype is found in notebook |
| 190 | +output. This allows for us to avoid having to embed `plotly.js` in the notebook output. The code for this is found under `js/src/mimeExtension.ts` and is compiled into `plotly/labextension` through `jupyter labextension build`, which is included in `npm run build`. |
| 191 | + |
172 | 192 | ### Configure black code formatting |
173 | 193 |
|
174 | 194 | This repo uses the [Black](https://black.readthedocs.io/en/stable/) code formatter, |
|
0 commit comments