Use Fira Math for matplotlib math rendering via custom fontset

.github/workflows/pages.yml

@@ -30,6 +30,7 @@ jobs:
         env:
           FONT_BASE: https://github.com/chrissimpkins/codeface/raw/master/fonts/code-new-roman
           OUTFIT_BASE: https://github.com/Outfitio/Outfit-Fonts/raw/main/fonts/ttf
+          FIRA_MATH_URL: https://github.com/firamath/firamath/releases/download/v0.3.4/FiraMath-Regular.otf
         run: |
           sudo apt-get update -y
           sudo apt-get install -y imagemagick fonts-inter
@@ -39,6 +40,7 @@ jobs:
           curl -fsSL "$FONT_BASE/Code%20New%20Roman-Regular.otf" -o /tmp/qpdk-fonts/CNR-Regular.otf
           curl -fsSL "$FONT_BASE/Code%20New%20Roman-Bold.otf" -o /tmp/qpdk-fonts/CNR-Bold.otf
           curl -fsSL "$FONT_BASE/Code%20New%20Roman-Italic.otf" -o /tmp/qpdk-fonts/CNR-Italic.otf
+          curl -fsSL "$FIRA_MATH_URL" -o /tmp/qpdk-fonts/FiraMath-Regular.otf
           sudo mkdir -p /usr/local/share/fonts/qpdk
           find /tmp/qpdk-fonts -type f \( -name '*.ttf' -o -name '*.otf' \) -exec sudo cp {} /usr/local/share/fonts/qpdk/ \;
           sudo fc-cache -f && rm -rf /tmp/qpdk-fonts

Makefile

@@ -11,6 +11,7 @@ JUST_CMD := uvx --from rust-just just
 
 # Font download URLs (Outfit from GitHub, Code New Roman from codeface; Inter via apt fonts-inter)
 FONT_BASE := https://github.com/chrissimpkins/codeface/raw/master/fonts/code-new-roman
+FIRA_MATH_URL := https://github.com/firamath/firamath/releases/download/v0.3.4/FiraMath-Regular.otf
 
 install-doc-fonts:
 	@if [ "$$GITHUB_ACTIONS" = "true" ]; then \
@@ -21,6 +22,7 @@ install-doc-fonts:
 		curl -fsSL "$(FONT_BASE)/Code%20New%20Roman-Regular.otf" -o /tmp/qpdk-fonts/CNR-Regular.otf && \
 		curl -fsSL "$(FONT_BASE)/Code%20New%20Roman-Bold.otf" -o /tmp/qpdk-fonts/CNR-Bold.otf && \
 		curl -fsSL "$(FONT_BASE)/Code%20New%20Roman-Italic.otf" -o /tmp/qpdk-fonts/CNR-Italic.otf && \
+		curl -fsSL "$(FIRA_MATH_URL)" -o /tmp/qpdk-fonts/FiraMath-Regular.otf && \
 		sudo mkdir -p /usr/local/share/fonts/qpdk && \
 	find /tmp/qpdk-fonts -type f \( -name '*.ttf' -o -name '*.otf' \) -exec sudo cp {} /usr/local/share/fonts/qpdk/ \; && \
 		sudo fc-cache -f && rm -rf /tmp/qpdk-fonts; \

docs/conf.py

@@ -16,7 +16,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.imgconverter",
     "sphinx.ext.intersphinx",
-    "sphinxcontrib.katex",
+    "sphinx.ext.mathjax",
     "sphinxcontrib.mermaid",
     "sphinxcontrib.svgbob",
     "sphinx_design",
@@ -89,6 +89,23 @@ def _qpdk_title(self, *args, **kwargs):
     "linkify",
 ]
 
+# -- MathJax configuration ---------------------------------------------------
+# NOTE: sphinx.ext.mathjax injects `window.MathJax = {options: {processHtmlClass: ...}}`
+# as a separate <script> tag BEFORE our mathjax4_config assignment.  The second
+# assignment overwrites the first, so we must include the Sphinx-required
+# `processHtmlClass` regex here too; otherwise MathJax ignores all math that
+# lives inside `<section class="mathjax_ignore">` elements (which is every
+# section in the Sphinx HTML output when MyST is used).
+mathjax4_config = {
+    "options": {
+        # Allow MathJax to process math nodes even inside mathjax_ignore regions.
+        "processHtmlClass": "tex2jax_process|mathjax_process|math|output_area",
+    },
+    "output": {
+        "font": "mathjax-fira",
+    },
+}
+
 # -- Notebook execution (myst-nb) --------------------------------------------
 nb_execution_mode = "cache"
 # Exclude HFSS notebooks from execution as they depend on Ansys HFSS

docs/qpdk.mplstyle

@@ -4,14 +4,21 @@
 # Fonts are chosen to match the Sphinx documentation theme (see docs/_static/css/custom.css):
 #   - Body text / labels / ticks: Inter (Google Fonts, sans-serif)
 #   - Figure titles:              Outfit (Google Fonts, sans-serif — applied via ipython_config.py)
+#   - Math text:                  Fira Math (https://github.com/firamath/firamath, OFL)
 #   - Monospace:                  Code New Roman (cdnfonts / codeface, OFL)
 
 font.family: sans-serif
 font.sans-serif: Inter, DejaVu Sans, Helvetica, Arial, sans-serif
 font.monospace: Code New Roman, DejaVu Sans Mono, Courier New, Courier, monospace
 
-# Use Computer Modern math fonts for consistent LaTeX-like math rendering
-mathtext.fontset: cm
+# Use Fira Math for math rendering (custom fontset, no LaTeX backend needed)
+mathtext.fontset: custom
+mathtext.rm: Fira Math
+mathtext.it: Fira Math:italic
+mathtext.bf: Fira Math:bold
+mathtext.cal: Fira Math
+mathtext.sf: Fira Math
+mathtext.fallback: cm
 axes.formatter.use_mathtext: true
 
 # Titles use Outfit bold (font family is set via monkey-patch in ipython_config.py)

pyproject.toml

@@ -81,7 +81,6 @@ docs = [
   "sphinx-github-alerts>=1.0",
   "sphinxcontrib-bibtex",
   "sphinxcontrib-bibtex-urn",
-  "sphinxcontrib-katex",
   "sphinxcontrib-mermaid>=2.0.1",
   "sphinxcontrib-svgbob",
   { include-group = "docs-models" },