update

Author: AlexandreAndr

_quarto-book.yml

@@ -51,6 +51,10 @@ format:
     # is the single source of truth. Flexibility knobs:
     #   number-sections: false  -> turn numbering off entirely
     #   number-depth: 2         -> only number to e.g. 1.2 (not 1.2.8)
+    # Depth stays at 3 book-wide: several notebooks put an h4 directly under an
+    # h2, which at depth 4 renders a bogus zero component (e.g. "10.3.0.1"). A
+    # chapter that wants numbered h4s opts in via a per-directory _metadata.yml
+    # (see notebooks/Notebook_1/_metadata.yml).
     number-sections: true
     number-depth: 3
     execute:

notebooks/Notebook_1/Notebook_1a_Overview_and_Data_Representation.ipynb

@@ -268,7 +268,7 @@
     "id": "9D4gLiC3Q7DR"
    },
    "source": [
-    "# From Ideas to Code: Why Python?\n",
+    "## From Ideas to Code: Why Python?\n",
     "\n",
     "Once we define a learning problem, we need to work with the data directly.\n",
     "\n",
@@ -3147,7 +3147,19 @@
    "id": "294d8739",
    "metadata": {},
    "source": [
-    "### Example 1: The Identity Matrix\n",
+    "### Examples\n",
+    "\n",
+    "Five matrices, from the one that does nothing to one that does everything at once.\n",
+    "For each, watch both panels: the flow field tells you *where* space moves, the morphing\n",
+    "grid tells you *how* the whole plane is reshaped."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4e4b6e45",
+   "metadata": {},
+   "source": [
+    "#### Example 1: The Identity Matrix\n",
     "\n",
     "The identity matrix leaves every vector unchanged.\n",
     "\n",
@@ -3201,7 +3213,7 @@
    "id": "19537899",
    "metadata": {},
    "source": [
-    "### Example 2: Stretching Space\n",
+    "#### Example 2: Stretching Space\n",
     "\n",
     "This matrix stretches the first coordinate and slightly shrinks the second coordinate.\n",
     "\n",
@@ -3255,7 +3267,7 @@
    "id": "3821e02a",
    "metadata": {},
    "source": [
-    "### Example 3: Rotating Space\n",
+    "#### Example 3: Rotating Space\n",
     "\n",
     "A rotation matrix turns every point by the same angle.\n",
     "\n",
@@ -3311,7 +3323,7 @@
    "id": "483df675",
    "metadata": {},
    "source": [
-    "### Example 4: Mixing Features with a Shear\n",
+    "#### Example 4: Mixing Features with a Shear\n",
     "\n",
     "This matrix mixes the two coordinates.\n",
     "\n",
@@ -3365,7 +3377,7 @@
    "id": "efef5b10",
    "metadata": {},
    "source": [
-    "### Example 5: A General Transformation\n",
+    "#### Example 5: A General Transformation\n",
     "\n",
     "Now try a matrix that stretches, rotates, and mixes coordinates all at once.\n",
     "\n",

notebooks/Notebook_1/Notebook_1a_Overview_and_Data_Representation.py

@@ -182,7 +182,7 @@
 # > Who or what might be missing from the data?
 
 # %% [markdown] id="9D4gLiC3Q7DR"
-# # From Ideas to Code: Why Python?
+# ## From Ideas to Code: Why Python?
 #
 # Once we define a learning problem, we need to work with the data directly.
 #
@@ -1395,7 +1395,14 @@ def plot_matrix_flow_and_morph_gif(
 
 
 # %% [markdown]
-# ### Example 1: The Identity Matrix
+# ### Examples
+#
+# Five matrices, from the one that does nothing to one that does everything at once.
+# For each, watch both panels: the flow field tells you *where* space moves, the morphing
+# grid tells you *how* the whole plane is reshaped.
+
+# %% [markdown]
+# #### Example 1: The Identity Matrix
 #
 # The identity matrix leaves every vector unchanged.
 #
@@ -1417,7 +1424,7 @@ def plot_matrix_flow_and_morph_gif(
 )
 
 # %% [markdown]
-# ### Example 2: Stretching Space
+# #### Example 2: Stretching Space
 #
 # This matrix stretches the first coordinate and slightly shrinks the second coordinate.
 #
@@ -1439,7 +1446,7 @@ def plot_matrix_flow_and_morph_gif(
 )
 
 # %% [markdown]
-# ### Example 3: Rotating Space
+# #### Example 3: Rotating Space
 #
 # A rotation matrix turns every point by the same angle.
 #
@@ -1463,7 +1470,7 @@ def plot_matrix_flow_and_morph_gif(
 )
 
 # %% [markdown]
-# ### Example 4: Mixing Features with a Shear
+# #### Example 4: Mixing Features with a Shear
 #
 # This matrix mixes the two coordinates.
 #
@@ -1485,7 +1492,7 @@ def plot_matrix_flow_and_morph_gif(
 )
 
 # %% [markdown]
-# ### Example 5: A General Transformation
+# #### Example 5: A General Transformation
 #
 # Now try a matrix that stretches, rotates, and mixes coordinates all at once.
 #

notebooks/Notebook_1/_metadata.yml

@@ -0,0 +1,11 @@
+# Per-directory Quarto metadata: applies to every notebook in this folder and
+# overrides the book-wide settings in _quarto-book.yml.
+#
+# Module 1 groups its matrix-transformation examples one level deeper (1.8.6
+# "Examples" -> 1.8.6.1 "Example 1: ..."), so it needs 4th-level headings
+# numbered. The book default stays at 3 because other notebooks put an h4
+# directly under an h2, which at depth 4 renders a bogus zero component
+# (e.g. "10.3.0.1").
+format:
+  html:
+    number-depth: 4

scripts/render_book.sh

@@ -35,6 +35,14 @@ while IFS= read -r nb; do
   cp "$nb" "$BUILD/$rel"
 done < <(find "$ROOT/notebooks" -name '*.ipynb')
 
+# Per-directory metadata (_metadata.yml) overrides the book-wide config for the
+# notebooks in that folder, so it has to be staged alongside them.
+while IFS= read -r meta; do
+  rel="${meta#"$ROOT"/}"
+  mkdir -p "$BUILD/$(dirname "$rel")"
+  cp "$meta" "$BUILD/$rel"
+done < <(find "$ROOT/notebooks" -name '_metadata.yml')
+
 # Render the book.
 ( cd "$BUILD" && "$QUARTO" render ) || { echo "render failed"; exit 1; }