Config options update

.circleci/create_conda_optional_env.sh

@@ -14,7 +14,7 @@ if [ ! -d $HOME/miniconda/envs/circle_optional ]; then
     ./miniconda.sh -b -p $HOME/miniconda
 
     # Create environment
-    # PYTHON_VERSION=3.6
+    # PYTHON_VERSION=2.7 or 3.5
     $HOME/miniconda/bin/conda create -n circle_optional --yes python=$PYTHON_VERSION \
 requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets
 

binder/requirements.txt

@@ -14,3 +14,5 @@ networkx
 scikit-image
 datashader
 pyarrow
+dash_core_components
+dash_html_components

doc/python/configuration-options.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.2'
+      jupytext_version: 1.3.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,9 +20,10 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.0
   plotly:
-    description: How to set configuration options of plotly graphs in python.
+    description: How to set the configuration options of figures using the Plotly
+      Python graphing library.
     display_as: file_settings
     language: python
     layout: base
@@ -33,40 +34,156 @@ jupyter:
     thumbnail: thumbnail/modebar-icons.png
 ---
 
+# Configuration Options 
 
-You can pass a `config` dictionary with all configurations options such as `scrollZoom`, `editable`, and `displayModeBar`. For the complete list of config options check out: https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js
+The `show()` method that you use to display your figures also accepts a `config` parameter.
+
+You can set the configuration options for your figure by passing a dictionary to this parameter which contains the options you want to set. 
+
+If you don't set an option's value, it will be automatically be set to the default value for that option. 
+
+For the complete list of configuration options and their defaults see: https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js
 
 ##### Enable Scroll Zoom
 
+This option allows users to zoom in and out of figures using the scroll wheel on their mouse and/or a two-finger scroll. 
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = dict({'scrollZoom': True})
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+##### Force The Modebar to Always Be Visible
+
+When users hover over a figure generated with plotly.py, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.
+
+By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to always be visible regardless of whether or not the user is currently hovering over the figure, set the displayModeBar attribute in the configuration of your figure to true.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = {'displayModeBar': True}
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+##### Never Display The Modebar
+
+When users hover over a figure generated with `plotly.py`, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.
+
+By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to never be visible, then set the `displayModeBar` attribute in the config of your figure to false.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = {'displayModeBar': False}
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+##### Display the `Edit Chart` Link
+
+Set `showLink` to `True` in order to make your figure editable on [Chart Studio](https://plot.ly/online-chart-maker). 
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = {'showLink': True}
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+### Display The `Edit In Chart Studio` Modebar Button
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = {'showEditInChartStudio': True}
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+##### Hide the Plotly Logo on the Modebar
+
 ```python
 import plotly.graph_objects as go
 
 fig = go.Figure()
 
+config = {'displaylogo': False}
+
 fig.add_trace(
     go.Scatter(
         x=[1, 2, 3],
         y=[1, 3, 1]))
 
-fig.show(config={'scrollZoom': True})
+fig.show(config=config)
 ```
 
-##### Display ModeBar
+##### Turn Off Responsiveness
+
+By default, figures you create with the `plotly.py` package are [responsive](https://en.wikipedia.org/wiki/Responsive_web_design). Responsive figures automatically change their height and width when the size of the window they are displayed in changes. This is true for figures which are displayed in web browsers on desktops and mobile, Jupyter Notebooks, and other [rendering](https://plot.ly/python/renderers/) environments. 
+
+Try resizing your browser window to see this behavior in effect on this page.
+
+If you would like to disable this default behavior and force your figures to always have the same height and width regardless of the window size, set the value of the `responsive` key to `False` in your figure's configuration dictionary.
 
 ```python
 import plotly.graph_objects as go
 
 fig = go.Figure()
 
+config = {'responsive': False}
+
 fig.add_trace(
     go.Scatter(
         x=[1, 2, 3],
         y=[1, 3, 1]))
 
-fig.show(config={'displayModeBar': True})
+fig.show(config=config)
 ```
 
-##### Edit Mode - change the title and axis titles
+##### Editable Mode
+
+In editable mode, users can edit the chart title, axis labels and trace names in the legend.
 
 ```python
 import plotly.graph_objects as go
@@ -81,27 +198,81 @@ fig.add_trace(
 fig.show(config={'editable': True})
 ```
 
-##### Multiple Config Options at Once!
+##### Making A Static Chart
 
 ```python
 import plotly.graph_objects as go
 
 fig = go.Figure()
 
+config = {'staticPlot': True}
+
 fig.add_trace(
     go.Scatter(
         x=[1, 2, 3],
         y=[1, 3, 1]))
 
-fig.show(config={
+fig.show(config=config)
+```
+
+##### Customize Download Plot Options
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = {
+  'toImageButtonOptions': {
+    'format': 'svg', # one of png, svg, jpeg, webp
+    'filename': 'custom_image',
+    'height': 500,
+    'width': 700,
+    'scale': 1 # Multiply title/legend/axis/canvas sizes by this factor
+  }
+}
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
+```
+
+##### Specifying Multiple Configuration Options Simultaneously!
+
+The dictionary that you use to specify configuration options for your figures can contain more than one configuration key/value pair. 
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+config = dict({
     'scrollZoom': True,
     'displayModeBar': True,
     'editable': True
 })
+
+fig.add_trace(
+    go.Scatter(
+        x=[1, 2, 3],
+        y=[1, 3, 1]))
+
+fig.show(config=config)
 ```
 
 ##### Remove Modebar Buttons
 
+To delete buttons from the modebar, pass an array of strings containing the names of the buttons you want to remove to the `modeBarButtonsToRemove` attribute in the figure's configuration dictionary. Note that different chart types have different default modebars. The following is a list of all the modebar buttons and the chart types they are associated with:
+
+-'2D': `zoom2d`, `pan2d`, `select2d`, `lasso2d`, `zoomIn2d`, `zoomOut2d`, `autoScale2d`, `resetScale2d`
+-'3D': `zoom3d`, `pan3d`, `rbitRotation`, `tableRotation`, `handleDrag3d`, `resetCameraDefault3d`, `resetCameraLastSave3d`, `hoverClosest3d`
+-'Cartesian': `hoverClosestCartesian`, `hoverCompareCartesian`
+-'Geo': `zoomInGeo`, `zoomOutGeo`, `resetGeo`, `hoverClosestGeo`
+-'Other': `hoverClosestGl2d`, `hoverClosestPie`, `toggleHover`, `resetViews`, `toImage: sendDataToCloud`, `toggleSpikelines`, `resetViewMapbox`
+
 ```python
 import plotly.graph_objects as go
 
@@ -117,13 +288,15 @@ fig.show(config={
 })
 ```
 
-### Double-click Delay
-Sets the maximum delay between two consecutive clicks to be interpreted as a double-click in ms. This is the time interval between first mousedown, and' second mouseup. The default timing is 300 ms (less than half a second).
-This setting propagates to all on-subplot double clicks (except for geo and mapbox). 
+### Double Click Delay
+Sets the maximum delay between two consecutive clicks to be interpreted as a double-click in `ms`. This is the time interval between first mousedown and second mouseup. The default timing is 300 ms (less than half a second).
+This setting propagates to all on-subplot double clicks (except for `geo` and `mapbox`). 
 
 ```python
 import plotly.graph_objects as go
 
+config = {'doubleClickDelay': 1000}
+
 fig = go.Figure(go.Bar(
     y = [3, 5, 3, 2],
     x = ["2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"],
@@ -132,7 +305,52 @@ fig = go.Figure(go.Bar(
 
 fig.update_layout(xaxis = {'type': 'date'})
 
-fig.show(config = {'doubleClickDelay': 1000})
+fig.show(config=config)
+```
+
+#### Configuring Figures in Dash Apps
+
+The same configuration dictionary that you pass to the `config` parameter of the `show()` method can also be passed to the `config` parameter of a `dcc.Graph` component.
+
+```python
+import dash
+import dash_core_components as dcc
+import dash_html_components as html
+
+external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
+
+app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
+
+config = dict({
+    'scrollZoom': True,
+    'displayModeBar': True,
+    'editable': True
+})
+
+app.layout = html.Div(children=[
+    html.H1(children='Hello Dash'),
+
+    html.Div(children='''
+        Dash: A web application framework for Python.
+    '''),
+
+    dcc.Graph(
+        id='example-graph',
+        figure={
+            'data': [
+                {'x': [1, 2, 3], 'y': [4, 1, 2], 'type': 'bar', 'name': 'SF'},
+                {'x': [1, 2, 3], 'y': [2, 4, 5], 'type': 'bar', 'name': u'Montréal'},
+            ],
+            'layout': {
+                'title': 'Dash Data Visualization'
+            }
+        },
+        config=config
+    )
+])
+
+# if __name__ == '__main__':
+    # app.run_server(debug=True)
 ```
 
 #### Reference

doc/requirements.txt

@@ -24,3 +24,5 @@ pathlib
 python-frontmatter
 datashader
 pyarrow
+dash_core_components
+dash_html_components