Add plotly backend and gallery prototype (#61)

* plotly backend proof of concept

* be more consistend with kwarg handling and defaults

* restructure backend dependencies and install process

* fix typo in bokeh's remove_ticks

* complete plotly backend

* gallery prototype

* extend docs and tests

* add plotly equivalences to glossary

* more sensible defaults and kwarg handling

* automate gallery generation via sphinx extension

* figsize and gallery related fixes

* full fledged gallery

* remove unused references

* update gallery generator

* initial plotly support for styles

* fix gallery generator processing

.gitignore

@@ -96,6 +96,9 @@ instance/
 docs/_build/
 docs/build
 docs/source/api/**/generated
+docs/source/gallery/_images
+docs/source/gallery/_scripts
+docs/source/gallery/*.md
 docs/jupyter_execute
 docs/source/api/backend/matplotlib.rst
 docs/source/api/backend/bokeh.rst

.pre-commit-config.yaml

@@ -16,6 +16,7 @@ repos:
   rev: 23.3.0
   hooks:
   - id: black
+    exclude: ^docs/source/gallery/
 
 - repo: https://github.com/pycqa/pydocstyle
   rev: 6.3.0
@@ -36,3 +37,4 @@ repos:
           "-rn", # Only display messages
           "-sn", # Don't display the score
         ]
+      exclude: ^docs/source/gallery/

.readthedocs.yaml

@@ -16,3 +16,6 @@ python:
      path: .
      extra_requirements:
        - doc
+       - matplotlib
+       - bokeh
+       - plotly

docs/source/_static/custom.css

@@ -1,9 +1,116 @@
+/* -------------------- THEME OVERRIDES -------------------- */
 html[data-theme="light"] {
   --pst-color-primary: rgb(11 117 145);
   --pst-color-secondary: rgb(238 144 64);
+  --pst-color-plot-background: rgb(255, 255, 255);
 }
 
 html[data-theme="dark"] {
   --pst-color-primary: rgb(0 192 191);
   --pst-color-secondary: rgb(238 144 64);
+  --pst-color-plot-background: rgb(218, 219, 220);
 }
+
+/* Override for example gallery - remove border around card */
+.bd-content div.sd-card.example-gallery {
+  border: none;
+}
+
+/* -------------------- EXAMPLE GALLERY + (homepage) -------------------- */
+
+/* Homepage - grid layout */
+.home-flex-grid {
+  display: flex;
+  flex-flow: row wrap;
+  justify-content: center;
+  gap: 10px;
+  padding: 20px 0px 40px;
+}
+
+/* Homepage + Example Gallery Body - Set dimensions */
+.home-img-plot,
+.bd-content div.sd-card.example-gallery .sd-card-body,
+.home-img-plot-overlay,
+.example-img-plot-overlay {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  overflow: hidden;
+  padding: 10px;
+}
+.home-img-plot,
+.home-img-plot-overlay {
+  width: 235px;
+  height: 130px;
+}
+.bd-content div.sd-card.example-gallery .sd-card-body,
+.example-img-plot-overlay {
+  width: 100%;
+  height: 150px;
+}
+.home-img-plot img,
+.bd-content div.sd-card.example-gallery .sd-card-body img {
+  /* Images keep aspect ratio and fit in container */
+  /* To make images stretch/fill container, change to min-width */
+  max-width: 100%;
+  max-height: 100%;
+}
+
+/* Homepage + Example Gallery Body - Set color and hover */
+.home-img-plot.img-thumbnail,
+.bd-content div.sd-card.example-gallery .sd-card-body {
+  background-color: var(--pst-color-plot-background);  /* Same as img-thumbnail from pydata css, adjusted for dark mode */
+}
+.home-img-plot-overlay,
+.example-img-plot-overlay,
+.bd-content div.sd-card.example-gallery .sd-card-body {
+  border: 1px solid #dee2e6;  /* Same as img-thumbnail from pydata css */
+  border-radius: 0.25rem;  /* Same as img-thumbnail from pydata css */
+}
+.home-img-plot-overlay,
+.example-img-plot-overlay,
+.example-img-plot-overlay p.sd-card-text {
+  background: var(--pst-color-primary);
+  position: absolute;
+  color: var(--pst-color-background);
+  opacity: 0;
+  transition: .2s ease;
+  text-align: center;
+  padding: 10px;
+  z-index: 998;  /* Make sure overlay is above image...this is here to handle dark mode */
+}
+.home-img-plot-overlay:hover,
+.bd-content div.sd-card.example-gallery:hover .example-img-plot-overlay,
+.example-img-plot-overlay p.sd-card-text {
+  opacity: 90%;
+}
+
+/* Example Gallery Body - Set syntax highlighting for code on hover */
+.example-img-plot-overlay .sd-card-text code.code {
+  background-color: var(--pst-color-background);
+}
+.example-img-plot-overlay .sd-card-text .code span.pre {
+  color: var(--pst-color-primary);
+  font-weight: 700;
+}
+
+/* Example Gallery Footer - Plot titles goes here */
+.example-gallery .sd-card-footer {
+  height: 40px;
+  padding: 5px;
+  border-top: none !important;
+}
+.example-gallery .sd-card-footer p.sd-card-text {
+  color: var(--pst-color-text-muted);
+  font-size: 1rem;  /* This is font size for plot titles (below the chart) */
+  font-weight: 700;
+}
+.sd-card.example-gallery:hover .sd-card-footer p.sd-card-text {
+  color: var(--pst-color-primary);  /* Change text color on hover over card */
+}
+
+/* Overlapping */
+.example-gallery a.sd-stretched-link.reference {
+  z-index: 999;  /* Countermeasure where z-index = 998 */
+}
+

docs/source/conf.py

@@ -1,5 +1,6 @@
 # pylint: disable=redefined-builtin,invalid-name
 import os
+import sys
 from importlib.metadata import metadata
 from pathlib import Path
 
@@ -25,6 +26,8 @@
 
 # -- General configuration
 
+sys.path.insert(0, os.path.abspath("../sphinxext"))
+
 extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
@@ -37,6 +40,8 @@
     "sphinx_design",
     "jupyter_sphinx",
     "matplotlib.sphinxext.plot_directive",
+    "bokeh.sphinxext.bokeh_plot",
+    "gallery_generator",
 ]
 
 templates_path = ["_templates"]
@@ -47,6 +52,7 @@
     ".ipynb_checkpoints",
     "**/*.template.rst",
     "**/*.part.rst",
+    "**/*.part.md",
 ]
 suppress_warnings = ["mystnb.unknown_mime_type"]
 
@@ -112,7 +118,7 @@
     "python": ("https://docs.python.org/3/", None),
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
-    "bokeh": ("https://docs.bokeh.org/en/2.4.3", None),
+    "bokeh": ("https://docs.bokeh.org/en/latest", None),
 }
 
 # -- Options for HTML output

docs/source/contributing/testing.md

@@ -55,6 +55,7 @@ but backend specific tests can be skipped when running the test suite:
 ```console
 tox -e py311 -- --skip-bokeh
 tox -e py311 -- --skip-mpl
+tox -e py311 -- --skip-plotly
 ```
 
 :::{note} It is also possible to use both flags, in which case, only tests

docs/source/gallery/distribution/plot_dist_ecdf.py

@@ -0,0 +1,27 @@
+"""
+(gallery_dist_ecdf)=
+# ECDF plot
+
+Facetted ECDF plots for 1D marginals of the distribution
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_dist`
+
+Other gallery examples using `plot_dist`: {ref}`gallery_dist_kde`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("centered_eight")
+pc = azp.plot_dist(
+    data,
+    kind="ecdf",
+    backend="none"  # change to preferred backend
+)
+pc.show()

docs/source/gallery/distribution/plot_dist_kde.py

@@ -0,0 +1,27 @@
+"""
+(gallery_dist_kde)=
+# KDE plot
+
+Facetted KDE plots for 1D marginals of the distribution
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_dist`
+
+Other gallery examples using `plot_dist`: {ref}`gallery_dist_ecdf`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("centered_eight")
+pc = azp.plot_dist(
+    data,
+    kind="kde",
+    backend="none"  # change to preferred backend
+)
+pc.show()

docs/source/gallery/distribution/plot_forest.py

@@ -0,0 +1,27 @@
+"""
+(gallery_forest)=
+# Forest plot
+
+Default forest plot with marginal distribution summaries
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_forest`
+
+Other gallery examples using `plot_forest`: {ref}`gallery_forest_shade`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("rugby")
+pc = azp.plot_forest(
+    data,
+    var_names=["home", "atts", "defs"],
+    backend="none"  # change to preferred backend
+)
+pc.show()

docs/source/gallery/distribution/plot_forest_shade.py

@@ -0,0 +1,28 @@
+"""
+(gallery_forest_shade)=
+# Forest plot with shading
+
+Forest plot marginal summaries with row shading to enhance reading
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_forest`
+
+Other gallery examples using `plot_forest`: {ref}`gallery_forest`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("rugby")
+pc = azp.plot_forest(
+    data,
+    var_names=["home", "atts", "defs"],
+    shade_label="team",
+    backend="none",  # change to preferred backend
+)
+pc.show()

docs/source/gallery/distribution_comparison/plot_dist_models.py

@@ -0,0 +1,29 @@
+"""
+(gallery_dist_models)=
+# Marginal distribution comparison plot
+
+Full marginal distribution comparison between different models
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_dist`
+
+Other gallery examples using `plot_dist`: {ref}`gallery_dist_kde`, {ref}`gallery_dist_ecdf`
+
+Other examples comparing marginal distributions: {ref}`gallery_forest_models`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+c = load_arviz_data("centered_eight")
+n = load_arviz_data("non_centered_eight")
+pc = azp.plot_dist(
+    {"Centered": c, "Non Centered": n},
+    backend="none"  # change to preferred backend
+)
+pc.show()

docs/source/gallery/distribution_comparison/plot_forest_models.py

@@ -0,0 +1,29 @@
+"""
+(gallery_forest_models)=
+# Forest plot comparison
+
+Forest plot summaries for 1D marginal distributions
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_forest`
+
+Other gallery examples using `plot_forest`: {ref}`gallery_forest`, {ref}`gallery_forest_shade`
+
+Other examples comparing marginal distributions: {ref}`gallery_dist_models`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+c = load_arviz_data("centered_eight")
+n = load_arviz_data("non_centered_eight")
+pc = azp.plot_forest(
+    {"Centered": c, "Non Centered": n},
+    backend="none"  # change to preferred backend
+)
+pc.show()

docs/source/gallery/inference_diagnostics/plot_trace.py

@@ -0,0 +1,24 @@
+"""
+(gallery_trace)=
+# Trace plot
+
+Facetted plot with MCMC traces for each variable
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_trace`
+:::
+"""
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("centered_eight")
+pc = azp.plot_trace(
+    data,
+    backend="none"  # change to preferred backend
+)
+pc.show()