Skip to content

Commit

Permalink
new extension docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicolaskruchten
nicolaskruchten committed Jun 20, 2021
1 parent 7595f4b commit 50fa0da
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 75 deletions.
37 changes: 17 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Our recommended IDE for Plotly’s Python graphing library is Dash Enterprise’

`pip install plotly==4.14.3`

Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.5"`):
Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):

```python
import plotly.graph_objects as go
Expand Down Expand Up @@ -95,48 +95,45 @@ or conda.
conda install -c plotly plotly=4.14.3
```

### Jupyter Notebook Support
### JupyterLab Support

For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using `pip`:

```
pip install "notebook>=5.3" "ipywidgets>=7.5"
$ pip install "jupyterlab>=3" "ipywidgets>=7.6"
```

or `conda`:

```
conda install "notebook>=5.3" "ipywidgets>=7.5"
$ conda install "jupyterlab>=3" "ipywidgets>=7.6"
```

### JupyterLab Support

For use in JupyterLab, install the `jupyterlab` and `ipywidgets`
packages using `pip`:
The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):

```
pip install jupyterlab "ipywidgets>=7.5"
# JupyterLab 2.x renderer support
jupyter labextension install [email protected] @jupyter-widgets/jupyterlab-manager
```

or `conda`:
Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

### Jupyter Notebook Support

For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
packages using `pip`:

```
conda install jupyterlab "ipywidgets>=7.5"
pip install "notebook>=5.3" "ipywidgets>=7.5"
```

Then run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
or `conda`:

```
# Basic JupyterLab renderer support
jupyter labextension install [email protected]
# OPTIONAL: Jupyter widgets extension for FigureWidget support
jupyter labextension install @jupyter-widgets/jupyterlab-manager [email protected]
conda install "notebook>=5.3" "ipywidgets>=7.5"
```

Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

### Static Image Export

plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
Expand Down
68 changes: 28 additions & 40 deletions doc/python/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
jupytext_version: 1.6.0
jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
Expand Down Expand Up @@ -34,7 +34,6 @@ jupyter:
- /python/pytables/
---

<!-- #region -->

### Overview

Expand Down Expand Up @@ -72,7 +71,6 @@ This package contains everything you need to write figures to standalone HTML fi

> Note: **No internet connection, account, or payment is required to use plotly.py.** Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below). **plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures or data to cloud services.**
<!-- #endregion -->

```python
import plotly.graph_objects as go
Expand All @@ -93,32 +91,28 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
IFrame(snippet_url + 'getting-started', width='100%', height=630)
```

<!-- #region -->

#### Jupyter Notebook Support
#### JupyterLab Support

For use in the classic [Jupyter Notebook](https://jupyter.org/), install the `notebook` and `ipywidgets`
For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using `pip`:

```
$ pip install "notebook>=5.3" "ipywidgets>=7.5"
$ pip install "jupyterlab>=3" "ipywidgets>=7.6"
```

or `conda`:

```
$ conda install "notebook>=5.3" "ipywidgets>=7.5"
$ conda install "jupyterlab>=3" "ipywidgets>=7.6"
```

These packages contain everything you need to run a Jupyter notebook...
These packages contain everything you need to run JupyterLab...

```
$ jupyter notebook
$ jupyter lab
```

and display plotly figures inline using the notebook renderer...

<!-- #endregion -->
and display plotly figures inline using the `plotly_mimetype` renderer...

```python
import plotly.graph_objects as go
Expand All @@ -134,65 +128,61 @@ fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig
```

<!-- #region -->
The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):

```
# JupyterLab 2.x renderer support
jupyter labextension install [email protected] @jupyter-widgets/jupyterlab-manager
```

Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.


See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.

#### JupyterLab Support

For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using `pip`:

```
$ pip install jupyterlab "ipywidgets>=7.6"
```
#### Jupyter Notebook Support

or `conda`:
For use in the classic [Jupyter Notebook](https://jupyter.org/), install the `notebook` and `ipywidgets`
packages using `pip`:

```
$ conda install jupyterlab "ipywidgets>=7.6"
$ pip install "notebook>=5.3" "ipywidgets>=7.5"
```

For JupyterLab 2 or earlier, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
or `conda`:

```
# JupyterLab renderer support
jupyter labextension install [email protected]
# OPTIONAL: Jupyter widgets extension
jupyter labextension install @jupyter-widgets/jupyterlab-manager [email protected]
$ conda install "notebook>=5.3" "ipywidgets>=7.5"
```

These packages contain everything you need to run JupyterLab...
These packages contain everything you need to run a Jupyter notebook...

```
$ jupyter lab
$ jupyter notebook
```

and display plotly figures inline using the `plotly_mimetype` renderer...
and display plotly figures inline using the notebook renderer...

<!-- #endregion -->

```python
import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
fig.show()
```

or using `FigureWidget` objects (if the "OPTIONAL" step above was executed).
or using `FigureWidget` objects.

```python
import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig
```

Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.

<!-- #region -->

See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.


### Static Image Export

plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
Expand Down Expand Up @@ -283,5 +273,3 @@ Once you've installed, you can use our documentation in three main ways:
For information on using Python to build web applications containing plotly figures, see the [_Dash User Guide_](https://dash.plotly.com/).

We also encourage you to join the [Plotly Community Forum](http://community.plotly.com/) if you want help with anything related to `plotly`.

<!-- #endregion -->
8 changes: 4 additions & 4 deletions doc/python/renderers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
jupytext_version: 1.6.0
jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
Expand All @@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
version: 3.7.6
version: 3.7.7
plotly:
description: Displaying Figures using Plotly's Python graphing library
display_as: file_settings
Expand Down Expand Up @@ -72,7 +72,7 @@ fig

> To be precise, figures will display themselves using the current default renderer when the two following conditions are true. First, the last expression in a cell must evaluate to a figure. Second, `plotly.py` must be running from within an `IPython` kernel.
**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (provided the `plotlywidget` JupyterLab extension is installed), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/).
**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/).

Additional contexts are supported by choosing a compatible renderer including the [IPython console](https://docs.spyder-ide.org/ipythonconsole.html), [QtConsole](https://qtconsole.readthedocs.io/en/stable/), [Spyder](https://www.spyder-ide.org/), and more.

Expand Down Expand Up @@ -169,7 +169,7 @@ This renderer may be useful when working with notebooks than contain lots of lar

###### `plotly_mimetype`

The `plotly_mimetype` renderer creates a specification of the figure (called a MIME-type bundle), and requests that the current user interface displays it. User interfaces that support this renderer include [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (requires the [`plotlywidget`](https://www.npmjs.com/package/plotlywidget) extension), [nteract](https://nteract.io/), and the Visual Studio Code [notebook interface](https://code.visualstudio.com/docs/python/jupyter-support).
The `plotly_mimetype` renderer creates a specification of the figure (called a MIME-type bundle), and requests that the current user interface displays it. User interfaces that support this renderer include [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), [nteract](https://nteract.io/), and the Visual Studio Code [notebook interface](https://code.visualstudio.com/docs/python/jupyter-support).

###### `jupyterlab`, `nteract`, and `vscode`
These are aliases for `plotly_mimetype` since this renderer is a good choice when working in JupyterLab, nteract, and the Visual Studio Code notebook interface. Note that in VSCode Notebooks, the version of Plotly.js that is used to render is provided by the [vscode-python extension](https://code.visualstudio.com/docs/languages/python) and often trails the latest version by several weeks, so the latest features of `plotly` may not be available in VSCode right away. The situation is similar for Nteract.
Expand Down
Loading

0 comments on commit 50fa0da

Please sign in to comment.