Merge branch 'main' into lazy-imports-perf

Author: cvanelteren

.github/workflows/build-ultraplot.yml

@@ -43,7 +43,7 @@ jobs:
 
       - name: Test Ultraplot
         run: |
-          pytest --cov=ultraplot --cov-branch --cov-report term-missing --cov-report=xml ultraplot
+          pytest -n auto --cov=ultraplot --cov-branch --cov-report term-missing --cov-report=xml ultraplot
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
@@ -71,29 +71,55 @@ jobs:
           cache-environment: true
           cache-downloads: false
 
+      # Cache Baseline Figures (Restore step)
+      - name: Cache Baseline Figures
+        id: cache-baseline
+        uses: actions/cache@v4
+        with:
+          path: ./ultraplot/tests/baseline # The directory to cache
+          # Key is based on OS, Python/Matplotlib versions, and the PR number
+          key: ${{ runner.os }}-baseline-pr-${{ github.event.pull_request.number }}-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}
+          restore-keys: |
+            ${{ runner.os }}-baseline-pr-${{ github.event.pull_request.number }}-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-
+
+      # Conditional Baseline Generation (Only runs on cache miss)
       - name: Generate baseline from main
+        # Skip this step if the cache was found (cache-hit is true)
+        if: steps.cache-baseline.outputs.cache-hit != 'true'
         run: |
-          mkdir -p baseline
+          mkdir -p ultraplot/tests/baseline
+          # Checkout the base branch (e.g., 'main') to generate the official baseline
           git fetch origin ${{ github.event.pull_request.base.sha }}
           git checkout ${{ github.event.pull_request.base.sha }}
+
+          # Install the Ultraplot version from the base branch's code
+          pip install --no-build-isolation --no-deps .
+
+          # Generate the baseline images and hash library
           python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
-          pytest -W ignore \
-            --mpl-generate-path=./baseline/ \
+          pytest -x -W ignore \
+            --mpl-generate-path=./ultraplot/tests/baseline/ \
             --mpl-default-style="./ultraplot.yml"\
             ultraplot/tests
-          git checkout ${{ github.sha }}  # Return to PR branch
 
+          # Return to the PR branch for the rest of the job
+          git checkout ${{ github.sha }}
+
+      # Image Comparison (Uses cached or newly generated baseline)
       - name: Image Comparison Ultraplot
         run: |
+          # Re-install the Ultraplot version from the current PR branch
+          pip install --no-build-isolation --no-deps .
+
           mkdir -p results
           python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
-          pytest -W ignore \
-              --mpl \
-              --mpl-baseline-path=./baseline/ \
-              --mpl-results-path=./results/ \
-              --mpl-generate-summary=html \
-              --mpl-default-style="./ultraplot.yml" \
-              ultraplot/tests
+          pytest -x -W ignore \
+            --mpl \
+            --mpl-baseline-path=./ultraplot/tests/baseline \
+            --mpl-results-path=./results/ \
+            --mpl-generate-summary=html \
+            --mpl-default-style="./ultraplot.yml" \
+            ultraplot/tests
 
       # Return the html output of the comparison even if failed
       - name: Upload comparison failures

docs/_scripts/fetch_releases.py

@@ -2,9 +2,12 @@
 Dynamically build what's new page based on github releases
 """
 
-import requests, re
+import re
 from pathlib import Path
 
+import requests
+from m2r2 import convert
+
 GITHUB_REPO = "ultraplot/ultraplot"
 OUTPUT_RST = Path("whats_new.rst")
 
@@ -14,21 +17,10 @@
 
 def format_release_body(text):
     """Formats GitHub release notes for better RST readability."""
-    lines = text.strip().split("\n")
-    formatted = []
-
-    for line in lines:
-        line = line.strip()
-
-        # Convert Markdown ## Headers to RST H2
-        if line.startswith("## "):
-            title = line[3:].strip()  # Remove "## " from start
-            formatted.append(f"{title}\n{'~' * len(title)}\n")  # RST H2 Format
-        else:
-            formatted.append(line)
+    # Convert Markdown to RST using m2r2
+    formatted_text = convert(text)
 
     # Convert PR references (remove "by @user in ..." but keep the link)
-    formatted_text = "\n".join(formatted)
     formatted_text = re.sub(
         r" by @\w+ in (https://github.com/[^\s]+)", r" (\1)", formatted_text
     )

docs/colorbars_legends.py

@@ -469,3 +469,44 @@
 ax = axs[1]
 ax.legend(hs2, loc="b", ncols=3, center=True, title="centered rows")
 axs.format(xlabel="xlabel", ylabel="ylabel", suptitle="Legend formatting demo")
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_guides_decouple:
+#
+# Decoupling legend content and location
+# --------------------------------------
+#
+# Sometimes you may want to generate a legend using handles from specific axes
+# but place it relative to other axes. In UltraPlot, you can achieve this by passing
+# both the `ax` and `ref` keywords to :func:`~ultraplot.figure.Figure.legend`
+# (or :func:`~ultraplot.figure.Figure.colorbar`). The `ax` keyword specifies the
+# axes used to generate the legend handles, while the `ref` keyword specifies the
+# reference axes used to determine the legend location.
+#
+# For example, to draw a legend based on the handles in the second row of subplots
+# but place it below the first row of subplots, you can use
+# ``fig.legend(ax=axs[1, :], ref=axs[0, :], loc='bottom')``. If ``ref`` is a list
+# of axes, UltraPlot intelligently infers the span (width or height) and anchors
+# the legend to the appropriate outer edge (e.g., the bottom-most axis for ``loc='bottom'``
+# or the right-most axis for ``loc='right'``).
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+fig, axs = uplt.subplots(nrows=2, ncols=2, refwidth=2, share=False)
+axs.format(abc="A.", suptitle="Decoupled legend location demo")
+
+# Plot data on all axes
+state = np.random.RandomState(51423)
+data = (state.rand(20, 4) - 0.5).cumsum(axis=0)
+for ax in axs:
+    ax.plot(data, cycle="mplotcolors", labels=list("abcd"))
+
+# Legend 1: Content from Row 2 (ax=axs[1, :]), Location below Row 1 (ref=axs[0, :])
+# This places a legend describing the bottom row data underneath the top row.
+fig.legend(ax=axs[1, :], ref=axs[0, :], loc="bottom", title="Data from Row 2")
+
+# Legend 2: Content from Row 1 (ax=axs[0, :]), Location below Row 2 (ref=axs[1, :])
+# This places a legend describing the top row data underneath the bottom row.
+fig.legend(ax=axs[0, :], ref=axs[1, :], loc="bottom", title="Data from Row 1")

docs/conf.py

@@ -12,14 +12,14 @@
 # -- Imports and paths --------------------------------------------------------------
 
 # Import statements
-import os
-import sys
 import datetime
+import os
 import subprocess
-from pathlib import Path
+import sys
 
 # Surpress warnings from cartopy when downloading data inside docs env
 import warnings
+from pathlib import Path
 
 try:
     from cartopy.io import DownloadWarning
@@ -38,6 +38,7 @@
     if not hasattr(sphinx.util, "console"):
         # Create a compatibility layer
         import sys
+
         import sphinx.util
         from sphinx.util import logging
 
@@ -54,7 +55,7 @@ def __getattr__(self, name):
 # Build what's news page from github releases
 from subprocess import run
 
-run("python _scripts/fetch_releases.py".split(), check=False)
+run([sys.executable, "_scripts/fetch_releases.py"], check=False)
 
 # Update path for sphinx-automodapi and sphinxext extension
 sys.path.append(os.path.abspath("."))
@@ -63,7 +64,6 @@ def __getattr__(self, name):
 # Print available system fonts
 from matplotlib.font_manager import fontManager
 
-
 # -- Project information -------------------------------------------------------
 # The basic info
 project = "UltraPlot"
@@ -297,6 +297,11 @@ def __getattr__(self, name):
 
 # -- Options for HTML output -------------------------------------------------
 
+# Meta
+html_meta = {
+    "google-site-verification": "jrFbkSQGBUPSYP5LERld7DDSm1UtbMY9O5o3CdzHJzU",
+}
+
 # Logo
 html_logo = str(Path("_static") / "logo_square.png")