Improve plotly style guide (#7346)

doc/how_to/styling/plotly.md

@@ -1,26 +1,24 @@
 # Style Plotly Plots
 
-This guide addresses how to style Plotly plots displayed using the [Plotly pane](../../reference/panes/Plotly).
+This guide demonstrates how to style Plotly plots using the [Plotly pane](../../reference/panes/Plotly). You can customize your plots with Plotly's built-in templates, available in `plotly.io.templates`. For more details, refer to the [Plotly Templates Guide](https://plotly.com/python/templates/).
 
-Plotly provides a list of built in templates in `plotly.io.templates`. See the [Plotly Templates Guide](https://plotly.com/python/templates/).
-
-The gif below displays an example of what can be achieved with a little styling of the Plotly plot and the `FastListTemplate`.
+The GIF below illustrates the possibilities when you style a Plotly plot with `FastGridTemplate`.
 
 ![PlotlyStyle.gif](https://assets.holoviews.org/panel/thumbnails/gallery/styles/plotly-styles.gif)
 
-## A Plotly Express plot with a custom theme and accent color
+## Creating a Plotly Express Plot with a Custom Theme and Accent Color
 
-In this example we will give the Plotly Express plot a dark theme and a custom accent color.
+In this example, you'll apply a dark theme and a custom accent color to a Plotly Express plot.
 
 ```{pyodide}
 import pandas as pd
 import plotly.express as px
 import plotly.io as pio
-
 import panel as pn
 
 pn.extension("plotly")
 
+# Sample data
 data = pd.DataFrame(
  [
  ("Monday", 7),
@@ -34,53 +32,89 @@ data = pd.DataFrame(
  columns=["Day", "Orders"],
 )
 
+# Function to create the plot
 def plot(template, color):
  fig = px.line(
  data,
  x="Day",
  y="Orders",
  template=template,
- color_discrete_sequence=(color,),
+ color_discrete_sequence=[color],
  title=f"Template: {template}",
  )
  fig.update_traces(mode="lines+markers", marker=dict(size=10), line=dict(width=4))
  fig.layout.autosize = True
  return fig
 
+# Widget for template selection and color picker
 templates = sorted(pio.templates)
 template = pn.widgets.Select(value="plotly_dark", options=templates, name="Template")
 color = pn.widgets.ColorPicker(value="#F08080", name="Color")
 
+# Display the plot and widgets
 pn.Column(
  pn.Row(template, color),
  pn.pane.Plotly(pn.bind(plot, template, color), sizing_mode="stretch_width"),
  "**Plotly Templates**: " + ", ".join(templates),
 ).servable()
 ```
 
-## A Plotly `go.Figure` plot with dark theme
+## Styling a Plotly `go.Figure` Plot with a Dark Theme
 
-In this example we will give the Plotly `go.Figure` plot a dark theme.
+This example shows how to apply a dark theme to a Plotly `go.Figure` plot.
 
 ```{pyodide}
 import pandas as pd
 import plotly.graph_objects as go
-
 import panel as pn
 
 pn.extension("plotly")
 
-TEMPLATE = "plotly_dark" # "ggplot2", "seaborn", "simple_white", "plotly", "plotly_white", "plotly_dark", "presentation", "xgridoff", "ygridoff", "gridon", "none"
+# Choose a template
+TEMPLATE = "plotly_dark"
 
+# Load data for the plot
 z_data = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv")
 
+# Create a 3D surface plot
 fig = go.Figure(
  data=go.Surface(z=z_data.values),
  layout=go.Layout(
  title="Mt Bruno Elevation",
- ))
+ )
+)
 fig.layout.autosize = True
-fig.update_layout(template=TEMPLATE, title=f"Mt Bruno Elevation in a '{TEMPLATE}' template")
+fig.update_layout(template=TEMPLATE, title=f"Mt Bruno Elevation in '{TEMPLATE}' template")
 
+# Display the plot
 pn.pane.Plotly(fig, height=500, sizing_mode="stretch_width").servable()
 ```
+
+## Changing the Default Theme in Plotly Express
+
+You can change the default Plotly Express `template` based on the `pn.config.theme` setting:
+
+```python
+import plotly.express as px
+
+px.defaults.template = "plotly_dark" if pn.config.theme == "dark" else "plotly_white"
+```
+
+## Changing Plotly Template Defaults
+
+For example, you can set `paper_bgcolor` and `plot_bgcolor` to transparent:
+
+```python
+import plotly.io as pio
+
+for theme in ["plotly_dark", "plotly_white"]:
+ pio.templates[theme].layout.paper_bgcolor = 'rgba(0,0,0,0)'
+ pio.templates[theme].layout.plot_bgcolor = 'rgba(0,0,0,0)'
+ pio.templates[theme].layout.legend = dict(orientation="h", yanchor="bottom", y=-0.2)
+ pio.templates[theme].layout.bargap = 0.2
+```
+
+## Additional Examples
+
+- [Panel Iris Analysis | PY.CAFE](https://py.cafe/panel-org/panel-iris-analysis).
+- [Plotly Style Dashboard | PY.CAFE](https://py.cafe/panel-org/plotly-style-dashboard).

examples/reference/panes/Plotly.ipynb

@@ -26,7 +26,7 @@
  "source": [
  "## Parameters:\n",
  "\n",
- "For details on other options for customizing the component see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
+ "For details on other options for customizing the component see the general [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides as well as the specific [Style Plotly Plots](../../how_to/styling/plotly.md) how-to guide.\n",
  "\n",
  "### Core\n",
  "\n",
@@ -622,12 +622,12 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "\r\n",
- "\r\n",
- "### Parent-Child Views\r\n",
- "\r\n",
- "A common technique for exploring higher-dimensional datasets is the use of Parent-Child views. This approach allows you to employ a top-down method to initially exing thehree most important dimensions in the parent plot. You can then select a subset of the data points and examine them in greater detail and across additional dimensions.\r\n",
- "\r\n",
+ "\n",
+ "\n",
+ "### Parent-Child Views\n",
+ "\n",
+ "A common technique for exploring higher-dimensional datasets is the use of Parent-Child views. This approach allows you to employ a top-down method to initially exing thehree most important dimensions in the parent plot. You can then select a subset of the data points and examine them in greater detail and across additional dimensions.\n",
+ "\n",
  "Let's create a plot where Box or Lasso selections in the parent plot update a child plot. We will also customize the action bars using the `config` parameter."
  ]
  },

panel/io/state.py

@@ -484,7 +484,11 @@ def as_cached(self, key: str, fn: Callable[[], T], ttl: int = None, **kwargs) ->
 
  Note: Keyword arguments must be hashable.
 
- Example:
+ Pandas Example:
+
+ >>> data = pn.state.as_cached('data', pd.read_csv, filepath_or_buffer=DATA_URL)
+
+ Function Example:
 
  >>> def load_dataset(name):
  >>> # some slow operation that uses name to load a dataset....