Add a section on theming with Plotly templates to the getting started guide

Author: tpvasconcelos

cicd_utils/ridgeplot_examples/__init__.py

@@ -19,6 +19,12 @@ def load_basic() -> go.Figure:
     return main()
 
 
+def load_basic_dark() -> go.Figure:
+    from ._basic_dark import main
+
+    return main()
+
+
 def load_basic_hist() -> go.Figure:
     from ._basic_hist import main
 
@@ -45,6 +51,7 @@ def load_probly() -> go.Figure:
 
 ALL_EXAMPLES: list[Example] = [
     Example("basic", load_basic),
+    Example("basic_dark", load_basic_dark),
     Example("basic_hist", load_basic_hist),
     Example("lincoln_weather", load_lincoln_weather),
     Example("lincoln_weather_red_blue", load_lincoln_weather_red_blue),

cicd_utils/ridgeplot_examples/_basic_dark.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go
+
+
+def main() -> go.Figure:
+    import numpy as np
+
+    from ridgeplot import ridgeplot
+
+    rng = np.random.default_rng(42)
+    my_samples = [rng.normal(n, size=900) for n in range(6, 0, -2)]
+    fig = ridgeplot(samples=my_samples, template="plotly_dark")
+    fig.update_layout(height=400, width=800)
+
+    return fig
+
+
+if __name__ == "__main__":
+    fig = main()
+    fig.show()

docs/_static/charts/basic_dark.webp

@@ -287,3 +287,20 @@ fig = ridgeplot(
 ```{raw} html
 :file: ../_static/charts/lincoln_weather_red_blue.html
 ```
+
+## Theming with Plotly templates
+
+Since `ridgeplot` is built on top of Plotly, you can also theme your ridgeline plots using [Plotly's figure templates](https://plotly.com/python/templates/). Simply pass the name of a registered template (or any other valid template representation) to the {py:paramref}`~ridgeplot.ridgeplot.template` parameter. For instance, taking the basic example from the top of this page and applying the `"plotly_dark"` template:
+
+```python
+fig = ridgeplot(samples=my_samples, template="plotly_dark")
+fig.show()
+```
+
+```{raw} html
+:file: ../_static/charts/basic_dark.html
+```
+
+:::{note}
+Unless a custom {py:paramref}`~ridgeplot.ridgeplot.colorscale` is specified, the default colorscale will also be inferred from the specified template.
+:::

docs/getting_started/getting_started.md

@@ -9,6 +9,10 @@ Unreleased changes
 
 - Implement a new `template` parameter to allow users to specify a Plotly figure template ({gh-pr}`389`)
 
+### Documentation
+
+- Add a section on theming with Plotly templates to the getting started guide ({gh-pr}`389`)
+
 ### CI/CD
 
 - Bump actions/download-artifact from 7 to 8 ({gh-pr}`368`)