Merge pull request #17 from sbu-python-class/alt-text

work of matplotlib alt-text

Author: zingale

.github/workflows/docs-test.yml

@@ -0,0 +1,33 @@
+name: Doc test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  doc-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.14"
+        cache: "pip"
+
+    - name: Install Python dependencies
+      run: |
+        sudo apt-get install python3-pip graphviz
+        pip install -r requirements.txt
+        pip install ghp-import
+        PATH="${PATH}:${HOME}/.local/bin"
+
+    - name: Build book HTML
+      run: |
+        ./build_and_process.sh

.github/workflows/main.yml

@@ -11,11 +11,13 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
         python-version: "3.14"
         cache: "pip"
+
     - name: Install Python dependencies
       run: |
         sudo apt-get install python3-pip graphviz
@@ -25,7 +27,7 @@ jobs:
 
     - name: Build book HTML
       run: |
-        KERAS_BACKEND="torch" jupyter-book build ./content
+        ./build_and_process.sh
 
     - name: Push _build/html to gh-pages
       run: |

build_and_process.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+KERAS_BACKEND="torch" jupyter-book build content
+
+cd content/_build/html
+for i in $(grep -lR "# alt-text" | grep html)
+do
+  echo $i
+  ../../../parse_alt.py $i
+done

content/02-numpy/numpy-basics.ipynb

@@ -576,7 +576,7 @@
     "\n",
     "Multidimensional arrays are stored in a contiguous space in memory -- this means that the columns / rows need to be unraveled (flattened) so that it can be thought of as a single one-dimensional array.  Different programming languages do this via different conventions:\n",
     "\n",
-    "![](row_column_major.png)\n",
+    "![multidimensional array formatting, row-major vs. column-major](row_column_major.png)\n",
     "\n",
     "Storage order:\n",
     "\n",
@@ -780,7 +780,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.2"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

content/04-matplotlib/matplotlib-basics.ipynb

@@ -286,7 +286,8 @@
    ],
    "source": [
     "fig, ax = plt.subplots()\n",
-    "ax.imshow(m)"
+    "ax.imshow(m)\n",
+    "# alt-text: a plot of the Mandelbrot set"
    ]
   },
   {
@@ -313,7 +314,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

content/04-matplotlib/matplotlib-exercises.ipynb

@@ -125,7 +125,8 @@
    "source": [
     "fig, ax = plt.subplots()\n",
     "ax.scatter(x,y)\n",
-    "ax.errorbar(x, y, yerr=sigma, fmt=\"o\")"
+    "ax.errorbar(x, y, yerr=sigma, fmt=\"o\")\n",
+    "# alt-text: a plot showing data points with vertical error bars"
    ]
   },
   {
@@ -214,7 +215,8 @@
    ],
    "source": [
     "ax.plot(x, afit[0] + afit[1]*x + afit[2]*x*x )\n",
-    "fig"
+    "fig\n",
+    "# alt-text: a plot showing data points with error bars and a quadratic fit to them"
    ]
   },
   {
@@ -320,7 +322,8 @@
    "source": [
     "fig, ax = plt.subplots()\n",
     "ax.scatter(x,y)\n",
-    "ax.errorbar(x, y, yerr=sigma, fmt=\"o\", label=\"_nolegend_\")"
+    "ax.errorbar(x, y, yerr=sigma, fmt=\"o\", label=\"_nolegend_\")\n",
+    "# alt-text: a plot showing a noisy exponential dataset with error bars"
    ]
   },
   {
@@ -402,7 +405,8 @@
     "           label=r\"$a_0 = $ %f; $a_1 = $ %f\" % (afit[0], afit[1]))\n",
     "ax.plot(x, a0_orig*np.exp(a1_orig*x), \":\", label=\"original function\")\n",
     "ax.legend(numpoints=1, frameon=False)\n",
-    "fig"
+    "fig\n",
+    "# alt-text: a plot showing noisy exponential data points, a fit, and the original function"
    ]
   },
   {
@@ -589,7 +593,8 @@
    "source": [
     "npts = 128\n",
     "xx, f = single_freq_sine(npts)\n",
-    "plot_FFT(xx, f)"
+    "plot_FFT(xx, f)\n",
+    "# alt-text: a plot with 4 vertical panels showing (1) a sine (2) the Fourier transform of the sine (3) the power in Fourier space (4) the data transformed back to real space"
    ]
   },
   {
@@ -645,7 +650,8 @@
    ],
    "source": [
     "xx, f = single_freq_cosine(npts)\n",
-    "plot_FFT(xx, f)"
+    "plot_FFT(xx, f)\n",
+    "# alt-text: a plot with 4 vertical panes showing a single-mode cosine transformed to Fourier space and back"
    ]
   },
   {
@@ -701,7 +707,8 @@
    ],
    "source": [
     "xx, f = single_freq_sine_plus_shift(npts)\n",
-    "plot_FFT(xx, f)"
+    "plot_FFT(xx, f)\n",
+    "# alt-text: a plot with 4 vertical panes showing a single-mode sine with a phase shift transformed to Fourier space and back"
    ]
   },
   {
@@ -782,7 +789,8 @@
     "xx, f = two_freq_sine(npts)\n",
     "\n",
     "fig, ax = plt.subplots()\n",
-    "ax.plot(xx, f)"
+    "ax.plot(xx, f)\n",
+    "# alt-text: a plot showing a two-mode sine wave"
    ]
   },
   {
@@ -847,7 +855,8 @@
     "fig, ax = plt.subplots()\n",
     "ax.plot(kfreq, fk.real, label=\"real\")\n",
     "ax.plot(kfreq, fk.imag, \":\", label=\"imaginary\")\n",
-    "ax.legend(frameon=False)"
+    "ax.legend(frameon=False)\n",
+    "# alt-text: the FFT of our two-mode sine-wave showing two spikes"
    ]
   },
   {
@@ -915,7 +924,8 @@
    ],
    "source": [
     "fig, ax = plt.subplots()\n",
-    "ax.plot(xx, fkinv.real)"
+    "ax.plot(xx, fkinv.real)\n",
+    "# alt-text: a plot of a single-mode sine wave"
    ]
   },
   {
@@ -1278,7 +1288,8 @@
    ],
    "source": [
     "fig, ax = plt.subplots()\n",
-    "ax.plot(x[1:N-1], sol)"
+    "ax.plot(x[1:N-1], sol)\n",
+    "# alt-text: a plot showing a function that looks approximately like -sin(x)"
    ]
   },
   {
@@ -1305,7 +1316,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.2"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

content/05-scipy/scipy-basics-2.ipynb

@@ -538,7 +538,8 @@
     "x_fine = np.linspace(0, 20, 10*N)\n",
     "\n",
     "ax.scatter(x, y)\n",
-    "ax.plot(x_fine, f_exact(x_fine), ls=\":\", label=\"original function\")"
+    "ax.plot(x_fine, f_exact(x_fine), ls=\":\", label=\"original function\")\n",
+    "# alt-text: a figure showing data points and an interpolant passing through them"
    ]
   },
   {
@@ -578,7 +579,8 @@
     "ax.plot(x_fine, f_interp(x_fine), label=\"interpolant\")\n",
     "\n",
     "ax.legend(frameon=False, loc=\"best\")\n",
-    "fig"
+    "fig\n",
+    "# alt-text: a figure showing data points, an interpolant to them, and the original function we sampled"
    ]
   },
   {
@@ -666,7 +668,8 @@
     "fig, ax = plt.subplots()\n",
     "data = func(x, y)\n",
     "im = ax.imshow(data.T, extent=(0, 1, 0, 1), origin=\"lower\")\n",
-    "fig.colorbar(im, ax=ax)"
+    "fig.colorbar(im, ax=ax)\n",
+    "# alt-text: a heat-map figure showing a function with small-amplitude ripples"
    ]
   },
   {
@@ -714,7 +717,8 @@
    "source": [
     "fig, ax = plt.subplots()\n",
     "im = ax.imshow(coarse.T, extent=(0, 1, 0, 1), origin=\"lower\")\n",
-    "fig.colorbar(im, ax=ax)"
+    "fig.colorbar(im, ax=ax)\n",
+    "# alt-text: a heat-map showing coarsened representation of our function"
    ]
   },
   {
@@ -820,7 +824,8 @@
    "source": [
     "fig, ax = plt.subplots()\n",
     "im = ax.imshow(new_data.T, extent=(0, 1, 0, 1), origin=\"lower\")\n",
-    "fig.colorbar(im, ax=ax)"
+    "fig.colorbar(im, ax=ax)\n",
+    "# alt-text: a heat-map showing the reconstructed function via interpolation"
    ]
   },
   {
@@ -860,7 +865,8 @@
     "diff = new_data - data\n",
     "fig, ax = plt.subplots()\n",
     "im = ax.imshow(diff.T, origin=\"lower\", extent=(0, 1, 0, 1))\n",
-    "fig.colorbar(im, ax=ax)"
+    "fig.colorbar(im, ax=ax)\n",
+    "# alt-text: a heat-map showing the error in our interpolation.  It is better than 10%"
    ]
   },
   {
@@ -964,7 +970,8 @@
     "fig, ax = plt.subplots()\n",
     "ax.plot(x, f(x))\n",
     "ax.scatter(np.array([root]), np.array([f(root)]))\n",
-    "ax.grid()"
+    "ax.grid()\n",
+    "# alt-text: a plot of our function with the root represented as a point"
    ]
   },
   {
@@ -1104,7 +1111,8 @@
     "fig = plt.figure()\n",
     "ax = plt.axes(projection='3d')\n",
     "ax.plot(X[0,:], X[1,:], X[2,:])\n",
-    "fig.set_size_inches(8.0,6.0)"
+    "fig.set_size_inches(8.0,6.0)\n",
+    "# alt-text: a 3D line plot of the solution -- it is dominated by two lobe-like structures"
    ]
   },
   {
@@ -1192,13 +1200,14 @@
     "\n",
     "ax.plot(X[0,:], X[1,:], X[2,:])\n",
     "\n",
-    "ax.scatter(sol1.x[0], sol1.x[1], sol1.x[2], marker=\"x\", color=\"r\")\n",
-    "ax.scatter(sol2.x[0], sol2.x[1], sol2.x[2], marker=\"x\", color=\"r\")\n",
-    "ax.scatter(sol3.x[0], sol3.x[1], sol3.x[2], marker=\"x\", color=\"r\")\n",
+    "ax.scatter(sol1.x[0], sol1.x[1], sol1.x[2], marker=\"x\", color=\"C1\")\n",
+    "ax.scatter(sol2.x[0], sol2.x[1], sol2.x[2], marker=\"x\", color=\"C1\")\n",
+    "ax.scatter(sol3.x[0], sol3.x[1], sol3.x[2], marker=\"x\", color=\"C1\")\n",
     "\n",
     "ax.set_xlabel(\"x\")\n",
     "ax.set_ylabel(\"y\")\n",
-    "ax.set_zlabel(\"z\")"
+    "ax.set_zlabel(\"z\")\n",
+    "# alt-text: the 3D solution again represented as a line / trajectory, now with the stable-points marked"
    ]
   },
   {
@@ -1342,7 +1351,8 @@
     "ax.loglog(ts, Ys[2,:], label=r\"$y_3$\")\n",
     "\n",
     "ax.legend(loc=\"best\", frameon=False)\n",
-    "ax.set_xlabel(\"time\")"
+    "ax.set_xlabel(\"time\")\n",
+    "# alt-text: the time-evolution of the species on a log scale"
    ]
   },
   {
@@ -1373,7 +1383,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.3"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

content/05-scipy/scipy-basics.ipynb

@@ -1,20 +1,20 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": 1,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "import numpy as np\n",
-    "import matplotlib.pyplot as plt"
+    "# More SciPy Exercises"
    ]
   },
   {
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": 1,
    "metadata": {},
+   "outputs": [],
    "source": [
-    "# More SciPy Exercises"
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt"
    ]
   },
   {
@@ -176,7 +176,8 @@
    ],
    "source": [
     "plt.plot(x, noisy)\n",
-    "plt.plot(x, orig)"
+    "plt.plot(x, orig)\n",
+    "# alt-text: a plot showing noisy sinusoidal and the original, un-noised data"
    ]
   },
   {
@@ -299,7 +300,8 @@
    "source": [
     "plt.plot(t, restrict_theta(y[0,:]))\n",
     "plt.xlabel(\"t\")\n",
-    "plt.ylabel(r\"$\\theta$\")"
+    "plt.ylabel(r\"$\\theta$\")\n",
+    "# alt-text: a plot showing many periods of a sinusoidal function"
    ]
   },
   {
@@ -367,7 +369,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.2"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,