Make docs builds fail on notebook execution errors and fix all doc issues

.gitignore

@@ -61,6 +61,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/sg_execution_times.rst
 
 # PyCharm
 .idea/

docs/changelog.md

@@ -4,6 +4,7 @@ _This project uses semantic versioning_
 
 ## UNRELEASED
 
+- Make docs builds fail on notebook execution errors and fix all doc issues [#369](https://github.com/egraphs-good/egglog-python/pull/369)
 - Add WIP `egglog.exp.any_expr` code for tracing arbitrary expressions with Python fallback [#366](https://github.com/egraphs-good/egglog-python/pull/366)
   - BREAKING: Remove support for Python 3.11 now that pyo3 has dropped support.
   - Allow mutating methods to update their underlying expression via `Expr.__replace_expr__`, and ensure default rewrites return the mutated receiver when using `mutates_self` or `mutates_first_arg`.

docs/conf.py

@@ -115,6 +115,7 @@
     "**.ipynb_checkpoints",
     "auto_examples/*.ipynb",
     # "auto_examples/*.md5",
+    "conf.py",  # Sphinx config file, not a notebook
 ]
 nitpicky = True
 
@@ -164,8 +165,7 @@
 # nb_execution_cache_path = ''
 
 # Exclude (POSIX) glob patterns for notebooks
-# nb_execution_excludepatterns = ()
-
+# Temporarily exclude notebooks with unrelated errors (not @egraph.class_ issues)
 # Execution timeout (seconds)
 nb_execution_timeout = 60 * 10
 
@@ -176,7 +176,7 @@
 # nb_execution_allow_errors = False
 
 # Raise an exception on failed execution, rather than emitting a warning
-nb_execution_raise_on_error = False
+nb_execution_raise_on_error = True
 
 # Print traceback to stderr on execution error
 nb_execution_show_tb = True

docs/explanation/2023_07_presentation.ipynb

@@ -465,7 +465,7 @@
    "source": [
     "## Open Source Data Science Ecosystem in Python\n",
     "\n",
-    "> <small>The term “ecosystem” is often used to describe the modern open-source scientific software. In biology, the term “ecosystem” is defined as a biological community of interacting organisms and their physical environment. Modern open-source scientific software development occurs in a similarly interconnected and interoperable fashion.</small>\n",
+    "> <small>The term \u201cecosystem\u201d is often used to describe the modern open-source scientific software. In biology, the term \u201cecosystem\u201d is defined as a biological community of interacting organisms and their physical environment. Modern open-source scientific software development occurs in a similarly interconnected and interoperable fashion.</small>\n",
     "\n",
     "<small>from [Jupyter Meets the Earth: Ecosystem](https://jupytearth.org/jupyter-resources/introduction/ecosystem.html)</small>\n",
     "\n",
@@ -984,7 +984,6 @@
     "egraph = EGraph()\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Structure(Expr): ...\n",
     "\n",
     "\n",
@@ -993,7 +992,7 @@
     "c = egraph.constant(\"c\", Structure)\n",
     "\n",
     "\n",
-    "@egraph.function\n",
+    "@function\n",
     "def operation(l: Structure, r: Structure) -> Structure: ...\n",
     "\n",
     "\n",
@@ -3057,7 +3056,6 @@
     "egraph = EGraph()\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Num(Expr):\n",
     "    @classmethod\n",
     "    def var(cls, name: StringLike) -> Num: ...\n",
@@ -5332,7 +5330,6 @@
     "egraph = EGraph()\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Bool(Expr):\n",
     "    def to_py(self) -> PyObject: ...\n",
     "\n",
@@ -5888,14 +5885,13 @@
     "egraph = EGraph()\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Num(Expr):\n",
     "    def __init__(self, i: i64Like) -> None: ...\n",
     "\n",
     "    def __add__(self, other: Num) -> Num: ...\n",
     "\n",
     "\n",
-    "@egraph.function\n",
+    "@function\n",
     "def fib(x: i64Like) -> Num: ...\n",
     "\n",
     "\n",
@@ -12099,4 +12095,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/explanation/2023_11_09_portland_state.ipynb

@@ -170,7 +170,7 @@
    "source": [
     "_What is built on top of this?_\n",
     "\n",
-    "> The term “ecosystem” is often used to describe the modern open-source scientific software. In biology, the term “ecosystem” is defined as a biological community of interacting organisms and their physical environment. Modern open-source scientific software development occurs in a similarly interconnected and interoperable fashion.\n",
+    "> The term \u201cecosystem\u201d is often used to describe the modern open-source scientific software. In biology, the term \u201cecosystem\u201d is defined as a biological community of interacting organisms and their physical environment. Modern open-source scientific software development occurs in a similarly interconnected and interoperable fashion.\n",
     "\n",
     "[Jupyter Meets the Earth: Ecosystem](https://jupytearth.org/jupyter-resources/introduction/ecosystem.html)\n"
    ]
@@ -313,7 +313,7 @@
    "source": [
     "## How do we manage the new complexity?\n",
     "\n",
-    "Integrated frameworks funded by companies with 💸?\n",
+    "Integrated frameworks funded by companies with \ud83d\udcb8?\n",
     "\n",
     "<img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/8/86/Google_JAX_logo.svg/1024px-Google_JAX_logo.svg.png\" width=\"200px\" align=\"center\"> <img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/c/c6/PyTorch_logo_black.svg/2560px-PyTorch_logo_black.svg.png\" width=\"200px\" align=\"center\"> <img src=\"https://miro.medium.com/v2/resize:fit:1400/0*kXleHB9RbdRW26Uy.png\" width=\"200px\" align=\"center\">\n"
    ]
@@ -465,14 +465,13 @@
     "\n",
     "\n",
     "# 1. Describe domain with types & functions\n",
-    "@egraph.class_\n",
     "class Num(Expr):\n",
     "    def __init__(self, i: i64Like) -> None: ...\n",
     "\n",
     "    def __add__(self, other: Num) -> Num: ...\n",
     "\n",
     "\n",
-    "@egraph.function(cost=20)\n",
+    "@function(cost=20)\n",
     "def fib(x: i64Like) -> Num: ..."
    ]
   },
@@ -545,7 +544,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "VBox(children=(IntSlider(value=0, max=6), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305…"
+       "VBox(children=(IntSlider(value=0, max=6), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305\u2026"
       ]
      },
      "execution_count": 3,
@@ -1474,7 +1473,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "VBox(children=(IntSlider(value=0, max=3), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305…"
+       "VBox(children=(IntSlider(value=0, max=3), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305\u2026"
       ]
      },
      "execution_count": 14,
@@ -1509,7 +1508,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "VBox(children=(IntSlider(value=0, max=6), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305…"
+       "VBox(children=(IntSlider(value=0, max=6), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305\u2026"
       ]
      },
      "execution_count": 15,
@@ -1542,7 +1541,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "VBox(children=(IntSlider(value=0, max=9), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305…"
+       "VBox(children=(IntSlider(value=0, max=9), GraphvizWidget(dots=['digraph  {stylesheet=\"/var/folders/xn/05ktz305\u2026"
       ]
      },
      "execution_count": 16,
@@ -1731,4 +1730,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/explanation/2023_11_17_pytensor.ipynb

@@ -133,7 +133,6 @@
     "egraph = EGraph()\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Int(Expr):\n",
     "    def __init__(self, value: i64Like) -> None: ...\n",
     "\n",
@@ -144,7 +143,6 @@
     "converter(i64, Int, Int)\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class IntTuple(Expr):\n",
     "    def __init__(self, first: Int) -> None: ...\n",
     "\n",
@@ -183,7 +181,6 @@
     "Shape = IntTuple\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class Tensor(Expr):\n",
     "    def __init__(self, name: StringLike, shape: Shape) -> None: ...\n",
     "\n",
@@ -199,17 +196,15 @@
     "    yield rewrite(Tensor(name, shape).shape).to(shape)\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class UnaryOp(Expr):\n",
     "    def __call__(self, x: Tensor) -> Tensor: ...\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class BinaryOp(Expr):\n",
     "    def __call__(self, x: Tensor, y: Tensor) -> Tensor: ...\n",
     "\n",
     "\n",
-    "@egraph.function(cost=1)\n",
+    "@function(cost=1)\n",
     "def Squeeze(axis: IntTuple) -> UnaryOp: ...\n",
     "\n",
     "\n",
@@ -258,7 +253,6 @@
     "    yield (rewrite(Squeeze(axis=(i,))(x).shape[j]).to(x.shape[j], i > j))\n",
     "\n",
     "\n",
-    "@egraph.class_\n",
     "class OpType(Expr): ...\n",
     "\n",
     "\n",
@@ -267,11 +261,11 @@
     "ScalarDiv = egraph.constant(\"ScalarDiv\", OpType)\n",
     "\n",
     "\n",
-    "@egraph.function(cost=10)\n",
+    "@function(cost=10)\n",
     "def Reduce(scalar_op: OpType, axis: IntTuple) -> UnaryOp: ...\n",
     "\n",
     "\n",
-    "@egraph.function(cost=5)\n",
+    "@function(cost=5)\n",
     "def Elemwise(scalar_op: OpType) -> BinaryOp: ...\n",
     "\n",
     "\n",
@@ -2527,4 +2521,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 0
-}
+}