Compare JSON Figure artifacts in regression tests

.gitignore

@@ -2,6 +2,7 @@
 #  Project specific
 # ============================================================================
 
+docs/_static/charts
 docs/api/autogen
 docs/api/public
 

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
       - id: pretty-format-json
         args: [ --autofix, --no-sort-keys ]
         # ignore jupyter notebooks
-        exclude: (^.*\.ipynb$|^pyrightconfig\.json$)
+        exclude: (^.*\.ipynb$|^pyrightconfig\.json$|^tests/e2e/artifacts/.*\.json$)
       - id: pretty-format-json
         args: [ --autofix, --no-sort-keys, --indent=1, --no-ensure-ascii ]
         # only jupyter notebooks

MANIFEST.in

@@ -22,12 +22,13 @@ include docs/make.bat
 include docs/robots.txt
 include docs/_static/favicon.ico
 recursive-include docs *.md *.py *.rst
-recursive-include docs/_static/charts *.html *.webp *.jpeg
+recursive-include docs/_static/charts *.html *.webp
 recursive-include docs/_static/css *.css
 recursive-include docs/_static/img *.png *.webp *.svg *.gif *.jpg
 recursive-include docs/_static/js *.js
 recursive-include docs/_templates *.html
-prune docs/build
+prune docs/_build
+prune docs/_static/charts
 prune docs/api/autogen
 prune docs/api/public
 
@@ -37,6 +38,7 @@ recursive-include cicd_utils README.md *.py
 recursive-include misc *.py *.ipynb *.txt *.png
 recursive-include requirements *.txt
 recursive-include tests *.py
+recursive-include tests/e2e/artifacts *.jpeg *.json
 
 # Globally excluded patterns
 recursive-exclude * *.py[cod] *.egg-info __pycache__ .ipynb_checkpoints/*

Makefile

@@ -81,7 +81,7 @@ clean-all: clean-docs clean-build clean-pyc clean-cov clean-ci-caches clean-tox
 .PHONY: clean-docs
 clean-docs: ## remove documentation build artifacts
 	@echo "==> Removing documentation build artifacts..."
-	rm -fr docs/build/ docs/api/autogen/ docs/api/public/
+	rm -fr docs/_build/ docs/_static/charts docs/api/autogen/ docs/api/public/
 
 
 .PHONY: clean-build

cicd_utils/ridgeplot_examples/__init__.py

@@ -2,23 +2,15 @@
 
 from typing import TYPE_CHECKING
 
-import plotly.graph_objects as go
+from ridgeplot_examples._base import Example
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    import plotly.graph_objects as go
 
-
-def tighten_margins(fig: go.Figure, px: int = 0) -> go.Figure:
-    """Tighten the margins of a Plotly figure."""
-    if fig.layout.margin != go.layout.Margin():
-        # If the Figure's margins are different from the default values,
-        # we'll assume that the user has set these values intentionally
-        return fig
-    # If the Figure does not have a title, we'll leave 40px of space at the
-    # top to account for the Plotly toolbar. If the Figure does include
-    # a title, we'll leave the top margin with the default value.
-    margin_top = None if fig.layout.title.text else max(40, px)
-    return fig.update_layout(margin=dict(l=px, r=px, t=margin_top, b=px))
+__all__ = [
+    "ALL_EXAMPLES",
+    "Example",
+]
 
 
 def load_basic() -> go.Figure:
@@ -51,10 +43,10 @@ def load_probly() -> go.Figure:
     return main()
 
 
-ALL_EXAMPLES: list[tuple[str, Callable[[], go.Figure]]] = [
-    ("basic", load_basic),
-    ("basic_hist", load_basic_hist),
-    ("lincoln_weather", load_lincoln_weather),
-    ("lincoln_weather_red_blue", load_lincoln_weather_red_blue),
-    ("probly", load_probly),
+ALL_EXAMPLES: list[Example] = [
+    Example("basic", load_basic),
+    Example("basic_hist", load_basic_hist),
+    Example("lincoln_weather", load_lincoln_weather),
+    Example("lincoln_weather_red_blue", load_lincoln_weather_red_blue),
+    Example("probly", load_probly),
 ]

cicd_utils/ridgeplot_examples/_base.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import plotly.graph_objects as go
+from minify_html import minify
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+def tighten_margins(fig: go.Figure, px: int = 0) -> go.Figure:
+    """Tighten the margins of a Plotly figure."""
+    if fig.layout.margin != go.layout.Margin():
+        # If the Figure's margins are different from the default values,
+        # we'll assume that the user has set these values intentionally
+        return fig
+    # If the Figure does not have a title, we'll leave 40px of space at the
+    # top to account for the Plotly toolbar. If the Figure does include
+    # a title, we'll leave the top margin with the default value.
+    margin_top = None if fig.layout.title.text else max(40, px)
+    return fig.update_layout(margin=dict(l=px, r=px, t=margin_top, b=px))
+
+
+@dataclass
+class Example:
+    plot_id: str
+    figure_factory: Callable[[], go.Figure]
+
+    def __post_init__(self) -> None:
+        self.fig = self.figure_factory()  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    def to_html(self, path: Path, minify_html: bool) -> None:
+        fig = deepcopy(self.fig)
+
+        if fig.layout.height is None:
+            raise ValueError("The Figure's layout.height value must be explicitly set.")
+        # Overriding the width to None results in a '100%' CSS width.
+        # This is achieved by setting the `default_width` parameter
+        # in `fig.to_html()` to "100%" (see below).
+        fig.layout.width = None
+
+        fig = tighten_margins(fig)
+
+        # Plotly.js (and MathJax.js if needed) should be included HTML's <head>
+        # of the Sphinx documentation. This can be done using the `html_js_files`
+        # configuration option in `conf.py`. For pages with multiple Plotly charts,
+        # this method is more efficient than including the Plotly.js (+ MathJax.js)
+        # source code in each HTML artefact. See `include_plotlyjs` below.
+        html_str = fig.to_html(
+            include_plotlyjs=False,
+            include_mathjax=False,
+            full_html=False,
+            default_width="100%",
+            div_id=f"plotly-id-{self.plot_id}",
+        )
+
+        # Wrap the chart's HTML in a <div> tag with a custom class name
+        # to allow for custom styling in the Sphinx documentation.
+        # See: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files
+        wrapper_div_class = "plotly-graph-wrapper"
+        html_str = f'<div class="{wrapper_div_class}">{html_str}</div>'
+        if minify_html:
+            # Need to set `minify_js` to False to avoid breaking
+            # the inner HTML set in the `hovertemplate` attribute
+            # TODO: Investigate if this is still necessary or find a workaround
+            #       (reason: minify_js seems to make a significant difference)
+            html_str = minify(html_str, minify_js=False)
+
+        if not path.exists():
+            path.mkdir(parents=True)
+        out_path = path / f"{self.plot_id}.html"
+        out_path.write_text(html_str, "utf-8")
+
+    def to_webp(self, path: Path) -> None:
+        fig = deepcopy(self.fig)
+        fig = tighten_margins(fig, px=40)
+        if not path.exists():
+            path.mkdir(parents=True)
+        out_image = path / f"{self.plot_id}.webp"
+        fig.write_image(
+            out_image,
+            format="webp",
+            width=fig.layout.width,
+            height=fig.layout.height,
+            scale=3,
+            engine="kaleido",
+        )
+
+    def to_jpeg(self, path: Path) -> None:
+        fig = deepcopy(self.fig)
+        fig = tighten_margins(fig, px=40)
+        if not path.exists():
+            path.mkdir(parents=True)
+        out_image = path / f"{self.plot_id}.jpeg"
+        fig.write_image(
+            out_image,
+            format="jpeg",
+            width=fig.layout.width,
+            height=fig.layout.height,
+            scale=1,
+            engine="kaleido",
+        )
+
+    def to_json(self, path: Path) -> None:
+        if not path.exists():
+            path.mkdir(parents=True)
+        out_path = path / f"{self.plot_id}.json"
+        out_path.write_text(self.fig.to_json(), "utf-8")

docs/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?= --show-traceback --write-all
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help: