You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/python/renderers.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,14 +40,14 @@ Plotly's Python graphing library, `plotly.py`, gives you a wide range of options
40
40
41
41
In general, there are six different approaches you can take in order to display `plotly` figures:
42
42
43
-
1. Using the `renderers` framework in the context of a script or notebook (the main topic of this page)
44
-
2. Using [Dash](https://dash.plot.ly) in a web app context
45
-
3. Using [Plotly Studio](https://plotly.com/studio) to generate charts using natural language
46
-
4. Using a [`FigureWidget` rather than a `Figure`](https://plotly.com/python/figurewidget/) in an [`ipywidgets` context](https://ipywidgets.readthedocs.io/en/stable/)
47
-
5. By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser immediately or later
48
-
6. By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS and loading the resulting file in any viewer
43
+
- Using the `renderers` framework in the context of a script or notebook (the main topic of this page)
44
+
- Using [Plotly Studio](https://plotly.com/studio) to generate charts using natural language
45
+
- Using [Dash](https://dash.plot.ly) in a web app context
46
+
- Using a [`FigureWidget` rather than a `Figure`](https://plotly.com/python/figurewidget/) in an [`ipywidgets` context](https://ipywidgets.readthedocs.io/en/stable/)
47
+
- By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser immediately or later
48
+
- By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS and loading the resulting file in any viewer
49
49
50
-
Each of the first three approaches is discussed below.
50
+
Each of the first four approaches is discussed below.
51
51
52
52
### Displaying Figures Using The `renderers` Framework
53
53
@@ -122,16 +122,16 @@ In this section, we will describe the built-in renderers so that you can choose
122
122
Interactive renderers display figures using the plotly.js JavaScript library and are fully interactive, supporting pan, zoom, hover tooltips, etc.
123
123
124
124
###### `notebook`
125
-
This renderer is intended for use in the classic [Jupyter Notebook](https://jupyter.org/install.html) (not JupyterLab). The full plotly.js JavaScript library bundle is added to the notebook the first time a figure is rendered, so this renderer will work without an Internet connection.
125
+
This renderer is intended for use in the classic [Jupyter Notebook](https://jupyter.org/install.html) (not JupyterLab). The full plotly.js JavaScript library bundle is added to the notebook the first time a figure is rendered, so this renderer will work without an internet connection.
126
126
127
-
This renderer is a good choice for notebooks that will be exported to HTML files (Either using [nbconvert](https://nbconvert.readthedocs.io/en/latest/) or the "Download as HTML" menu action) because the exported HTML files will work without an Internet connection.
127
+
This renderer is a good choice for notebooks that will be exported to HTML files (Either using [nbconvert](https://nbconvert.readthedocs.io/en/latest/) or the "Download as HTML" menu action) because the exported HTML files will work without an internet connection.
128
128
129
-
> Note: Adding the plotly.js bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an Internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.
129
+
> Note: Adding the plotly.js bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.
130
130
131
131
###### `notebook_connected`
132
-
This renderer is the same as `notebook` renderer, except the plotly.js JavaScript library bundle is loaded from an online CDN location. This saves a few megabytes in notebook size, but an Internet connection is required in order to display figures that are rendered this way.
132
+
This renderer is the same as `notebook` renderer, except the plotly.js JavaScript library bundle is loaded from an online CDN location. This saves a few megabytes in notebook size, but an internet connection is required in order to display figures that are rendered this way.
133
133
134
-
This renderer is a good choice for notebooks that will be shared with [nbviewer](https://nbviewer.jupyter.org/) since users must have an active Internet connection to access nbviewer in the first place.
134
+
This renderer is a good choice for notebooks that will be shared with [nbviewer](https://nbviewer.jupyter.org/) since users must have an active internet connection to access nbviewer in the first place.
135
135
136
136
###### `kaggle` and `azure`
137
137
These are aliases for `notebook_connected` because this renderer is a good choice for use with [Kaggle kernels](https://www.kaggle.com/docs/notebooks) and [Azure Notebooks](https://notebooks.azure.com/).
@@ -150,7 +150,7 @@ This renderer will open a figure in a browser tab using the default web browser.
150
150
These renderers are the same as the `browser` renderer, but they force the use of a particular browser.
151
151
152
152
###### `iframe` and `iframe_connected`
153
-
These renderers write figures out as standalone HTML files and then display [`iframe`](https://www.w3schools.com/html/html_iframe.asp) elements that reference these HTML files. The `iframe` renderer will include the plotly.js JavaScript bundle in each HTML file that is written, while the `iframe_connected` renderer includes only a reference to an online CDN location from which to load plotly.js. Consequently, the `iframe_connected` renderer outputs files that are smaller than the `iframe` renderer, but it requires an Internet connection while the `iframe` renderer can operate offline.
153
+
These renderers write figures out as standalone HTML files and then display [`iframe`](https://www.w3schools.com/html/html_iframe.asp) elements that reference these HTML files. The `iframe` renderer will include the plotly.js JavaScript bundle in each HTML file that is written, while the `iframe_connected` renderer includes only a reference to an online CDN location from which to load plotly.js. Consequently, the `iframe_connected` renderer outputs files that are smaller than the `iframe` renderer, but it requires an internet connection while the `iframe` renderer can operate offline.
154
154
155
155
This renderer may be useful when working with notebooks than contain lots of large figures. When using the `notebook` or `notebook_connected` renderer, all of the data for all of the figures in a notebook are stored inline in the notebook itself. If this would result in a prohibitively large notebook size, an `iframe` or `iframe_connected` renderer could be used instead. With the `iframe` renderers, the figure data are stored in the individual HTML files rather than in the notebook itself, resulting in a smaller notebook size.
156
156
@@ -165,7 +165,7 @@ The `plotly_mimetype` renderer creates a specification of the figure (called a M
165
165
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.
166
166
167
167
##### Static Image Renderers
168
-
A set of renderers is provided for displaying figures as static images. See the [Static Image Export](https://plot.ly/python/static-image-export/) page for more information on getting set up.
168
+
A set of renderers is provided for displaying figures as static images. See the [Static Image Export](https://plotly.com/python/static-image-export/) page for more information on getting set up.
169
169
170
170
###### `png`, `jpeg`, and `svg`
171
171
These renderers display figures as static `.png`, `.jpeg`, and `.svg` files, respectively. These renderers are useful for user interfaces that do not support inline HTML output, but do support inline static images. Examples include the [QtConsole](https://qtconsole.readthedocs.io/en/stable/), [Spyder](https://www.spyder-ide.org/), and the PyCharm [notebook interface](https://www.jetbrains.com/help/pycharm/jupyter-notebook-support.html).
@@ -188,7 +188,7 @@ This renderer displays figures as static PDF files. This is especially useful fo
188
188
In editors that support it (JupyterLab, nteract, and the Visual Studio Code notebook interface), this renderer displays the JSON representation of a figure in a collapsible interactive tree structure. This can be very useful for examining the structure of complex figures.
189
189
190
190
##### Multiple Renderers
191
-
You can specify that multiple renderers should be used by joining their names on `"+"` characters. This is useful when writing code that needs to support multiple contexts. For example, if a notebook specifies a default renderer string of `"notebook+plotly_mimetype+pdf"`then this notebook would be able to run in the classic Jupyter Notebook, in JupyterLab, and it would support being exported to PDF using `nbconvert`.
191
+
You can specify that multiple renderers should be used by joining their names on `"+"` characters. This is useful when writing code that needs to support multiple contexts. For example, if a notebook specifies a default renderer string of `"notebook+plotly_mimetype+pdf"`then this notebook would be able to run in the classic Jupyter Notebook, in JupyterLab, and it would support being exported to PDF using `nbconvert`.
192
192
193
193
#### Customizing Built-In Renderers
194
194
Most built-in renderers have configuration options to customize their behavior. To view a description of a renderer, including its configuration options, access the renderer object using dictionary-style key lookup on the `plotly.io.renderers` configuration object and then display it. Here is an example of accessing and displaying the `png` renderer.
0 commit comments