Docs: cache jupytext conversion and restore incremental html

docs/Makefile

@@ -12,7 +12,7 @@ BUILDDIR    = _build
 .PHONY: help clean html html-exec Makefile
 
 html:
-	@UPLT_DOCS_EXECUTE=$${UPLT_DOCS_EXECUTE:-always} $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" -E -a $(SPHINXOPTS)
+	@UPLT_DOCS_EXECUTE=$${UPLT_DOCS_EXECUTE:-auto} $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
 
 html-exec:
 	@UPLT_DOCS_EXECUTE=always $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" -E -a $(SPHINXOPTS)

docs/conf.py

@@ -403,15 +403,19 @@ def _reset_ultraplot(gallery_conf, fname):
     "color-spec": ":py:func:`color-spec <matplotlib.colors.is_color_like>`",
     "artist": ":py:func:`artist <matplotlib.artist.Artist>`",
 }
+# Keep autodoc aliases stable across builds so incremental Sphinx caching works.
+autodoc_type_aliases = dict(napoleon_type_aliases)
 
 # Fail on error. Note nbsphinx compiles all notebooks in docs unless excluded
 nbsphinx_allow_errors = False
 
 # Give *lots* of time for cell execution
 nbsphinx_timeout = 300
 
-# Add jupytext support to nbsphinx
-nbsphinx_custom_formats = {".py": ["jupytext.reads", {"fmt": "py:percent"}]}
+# Add jupytext support to nbsphinx with conversion cache.
+nbsphinx_custom_formats = {
+    ".py": ["sphinxext.jupytext_cache.reads_cached", {"fmt": "py:percent"}]
+}
 
 # Keep notebook output backgrounds theme-adaptive.
 nbsphinx_execute_arguments = [

docs/sphinxext/jupytext_cache.py

@@ -0,0 +1,51 @@
+"""
+Jupytext converter with a small on-disk cache for docs builds.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+
+import jupytext
+import nbformat
+
+
+def _get_cache_dir():
+    """
+    Return cache directory for converted jupytext notebooks.
+    """
+    override = os.environ.get("UPLT_DOCS_JUPYTEXT_CACHE_DIR", "").strip()
+    if override:
+        return Path(override).expanduser()
+    if os.environ.get("READTHEDOCS", "") == "True":
+        return Path.home() / ".cache" / "ultraplot" / "jupytext"
+    return Path(__file__).resolve().parent.parent / "_build" / ".jupytext-cache"
+
+
+def reads_cached(inputstring, *, fmt="py:percent"):
+    """
+    Convert Jupytext source to a notebook and cache by content hash.
+    """
+    disabled = os.environ.get("UPLT_DOCS_DISABLE_JUPYTEXT_CACHE", "").strip().lower()
+    if disabled in {"1", "true", "yes", "on"}:
+        return jupytext.reads(inputstring, fmt=fmt)
+
+    key = hashlib.sha256(
+        (fmt + "\0" + getattr(jupytext, "__version__", "") + "\0" + inputstring).encode(
+            "utf-8"
+        )
+    ).hexdigest()
+    cache_file = _get_cache_dir() / f"{key}.ipynb"
+    if cache_file.is_file():
+        try:
+            return nbformat.read(cache_file, as_version=4)
+        except Exception:
+            cache_file.unlink(missing_ok=True)
+
+    notebook = jupytext.reads(inputstring, fmt=fmt)
+    try:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+        nbformat.write(notebook, cache_file)
+    except Exception:
+        pass
+    return notebook