sphinx-exercise 1.2.0__tar.gz → 1.2.2__tar.gz

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/.github/workflows/ci.yml

@@ -91,7 +91,7 @@ jobs:
           pip install wheel build
           python -m build
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@v1.3.1
+        uses: pypa/gh-action-pypi-publish@v1.14.3
         with:
           user: __token__
           password: ${{ secrets.PYPI_KEY }}

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [v1.2.2](https://github.com/executablebooks/sphinx-exercise/tree/v1.2.2) (2026-11-10)
+
+### Fixes 🐛
+
+- Fixed `LaTeX Error: Not in outer par mode` when building LaTeX/PDF output with a captioned figure inside an exercise or solution ([#95](https://github.com/executablebooks/sphinx-exercise/pull/95))
+  - Figures inside exercise and solution boxes, including gated `exercise-start` / `solution-start` blocks, are now written as `\begin{figure}[H]` so they stay in place, as Sphinx already does for figures inside its own admonitions
+  - This also fixes `code-cell` outputs with `mystnb: figure: caption:` metadata inside a solution
+  - HTML output is unchanged
+- Fixed CI test failures on Sphinx 6 and 7 caused by a newer `pydata-sphinx-theme`, by switching the gated directive test root to the `alabaster` theme ([#88](https://github.com/executablebooks/sphinx-exercise/pull/88))
+
+## [v1.2.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.2.1) (2025-11-17)
+
+### Fixes 🐛
+
+- Fixed `ValueError: list.remove(x): x not in list` when building LaTeX/PDF output ([#82](https://github.com/executablebooks/sphinx-exercise/pull/82))
+  - Added defensive check before removing 'std-ref' class in `UpdateReferencesToEnumerated` transform
+  - The 'std-ref' class may not be present in all build scenarios (particularly LaTeX/PDF builds)
+  - Fix ensures compatibility across different Sphinx builders and versions
+- Fixed flaky CI tests caused by matplotlib font cache warning appearing in test output
+  - Added regex patterns to strip matplotlib font cache stderr messages from test regression fixtures
+
 ## [v1.2.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.2.0) (2025-11-05)
 
 ### New ✨

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sphinx-exercise
-Version: 1.2.0
+Version: 1.2.2
 Summary: A Sphinx extension for producing exercises and solutions.
 Project-URL: Homepage, https://github.com/executablebooks/sphinx-exercise
 Project-URL: Source, https://github.com/executablebooks/sphinx-exercise

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/docs/source/releases/index.md

@@ -5,6 +5,8 @@ This section contains detailed release notes for sphinx-exercise versions.
 ```{toctree}
 :maxdepth: 1
 
+v1.2.2
+v1.2.1
 v1.2.0
 v1.1.1
 v1.1.0

sphinx_exercise-1.2.2/docs/source/releases/v1.2.1.md

@@ -0,0 +1,69 @@
+# Release v1.2.1
+
+**Release Date**: November 17, 2025
+
+This is a patch release that fixes a bug causing build failures in LaTeX/PDF output.
+
+## 🐛 Bug Fixes
+
+### LaTeX/PDF Build Failure
+
+Fixed a `ValueError: list.remove(x): x not in list` error that occurred when building LaTeX/PDF documentation with sphinx-exercise v1.2.0 (#82).
+
+### CI Test Reliability
+
+Fixed flaky test failures in GitHub Actions CI caused by matplotlib font cache initialization warnings appearing in test output.
+
+**Issue:**
+- The `UpdateReferencesToEnumerated` transform attempted to remove the `'std-ref'` CSS class from inline reference nodes
+- In LaTeX/PDF builds (and potentially other build scenarios), this class may not be present
+- Python's `list.remove()` raises a `ValueError` when the item doesn't exist, causing the build to fail
+
+**Fix:**
+- Added a defensive check: `if "std-ref" in classes:` before attempting removal
+- The transform now safely handles cases where the class is absent
+- Preserves the intended behavior: converting textual references to numeric references for enumerated exercises
+
+**Impact:**
+- Fixes build failures in projects using sphinx-exercise with LaTeX/PDF output
+- No functional changes to existing behavior
+- All existing tests continue to pass
+
+**Example Error (before fix):**
+```
+Exception occurred:
+  File ".../sphinx_exercise/post_transforms.py", line 69, in run
+    classes.remove("std-ref")
+ValueError: list.remove(x): x not in list
+```
+
+## 📦 Installation
+
+Install or upgrade via pip:
+
+```bash
+pip install --upgrade sphinx-exercise
+```
+
+## 🔄 Migration Notes
+
+**If you're upgrading from v1.2.0:**
+- No breaking changes
+- No action required
+- If you encountered LaTeX/PDF build failures with v1.2.0, this release fixes that issue
+
+**Compatibility:**
+- Python 3.10, 3.11, 3.12, 3.13
+- Sphinx 6, 7, 8
+- All existing directives and configurations continue to work
+
+## 🔗 Related Issues
+
+- PR [#82](https://github.com/executablebooks/sphinx-exercise/pull/82) - Fix std-ref class removal
+- Issue discovered in [QuantEcon/continuous_time_mcs CI build](https://github.com/QuantEcon/continuous_time_mcs/actions/runs/19413054039/job/55537214078?pr=144)
+
+## 📚 Documentation
+
+For complete documentation, see:
+- [Configuration Options](../syntax.md)
+- [Installation Guide](../install.md)

sphinx_exercise-1.2.2/docs/source/releases/v1.2.2.md

@@ -0,0 +1,65 @@
+# Release v1.2.2
+
+**Release Date**: November 10, 2026
+
+This is a patch release that fixes LaTeX/PDF build failures when a captioned figure is placed inside an exercise or solution.
+
+## 🐛 Bug Fixes
+
+### Figures inside exercises and solutions in LaTeX/PDF output
+
+A figure with a caption inside an `exercise` or `solution` directive, including the gated `exercise-start` / `solution-start` forms, stopped the LaTeX build with `LaTeX Error: Not in outer par mode` (#94). In Jupyter Book projects this usually came from a `code-cell` with `mystnb: figure: caption:` metadata inside a solution. HTML output was not affected.
+
+**Cause:**
+- Sphinx writes figures inside its own admonitions as non-floating `\begin{figure}[H]`, because LaTeX does not allow a floating figure inside the admonition box
+- sphinx-exercise draws exercises and solutions with the same box, but did not tell Sphinx's LaTeX writer that it had opened one, so figures inside were written as floating `\begin{figure}[htbp]`
+
+**Fix:**
+- Exercise and solution boxes now update the same counter that Sphinx uses for its own admonitions, so figures inside them are written as `\begin{figure}[H]` and stay in place inside the box (#95)
+
+**Impact:**
+- LaTeX/PDF builds with captioned figures inside exercises or solutions now succeed
+- Figures outside exercise and solution boxes still float as before
+- HTML output is unchanged
+
+**Example Error (before fix):**
+```
+! LaTeX Error: Not in outer par mode.
+l.107 \begin{figure}[htbp]
+```
+
+### CI Test Reliability
+
+Fixed CI test failures on Sphinx 6 and 7 caused by a newer `pydata-sphinx-theme` release, by switching the gated directive test root to the `alabaster` theme (#88). This change only affects the test suite.
+
+## 📦 Installation
+
+Install or upgrade via pip:
+
+```bash
+pip install --upgrade sphinx-exercise
+```
+
+## 🔄 Migration Notes
+
+**If you're upgrading from v1.2.1:**
+- No breaking changes
+- No action required
+- If you removed figure captions inside exercises or solutions to work around this LaTeX error, you can now restore them
+
+**Compatibility:**
+- Python 3.10, 3.11, 3.12, 3.13
+- Sphinx 6, 7, 8
+- Sphinx 9 is not yet covered by the test suite (see #96)
+
+## 🔗 Related Issues
+
+- Issue [#94](https://github.com/executablebooks/sphinx-exercise/issues/94) - Figures inside exercise and solution boxes are written as floats in LaTeX
+- PR [#95](https://github.com/executablebooks/sphinx-exercise/pull/95) - Keep figures inside exercise and solution boxes from floating in LaTeX
+- PR [#88](https://github.com/executablebooks/sphinx-exercise/pull/88) - Use alabaster in the gated test root to unbreak CI
+
+## 📚 Documentation
+
+For complete documentation, see:
+- [Configuration Options](../syntax.md)
+- [Installation Guide](../install.md)

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/sphinx_exercise/__init__.py

@@ -7,7 +7,7 @@ This package is an extension for sphinx to support exercise and solutions.
 :license: MIT, see LICENSE for details.
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.2"
 
 from pathlib import Path
 from typing import Any, Dict, Set, Union, cast

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/sphinx_exercise/nodes.py

@@ -110,13 +110,25 @@ def is_extension_node(node):
 # Visit and Depart Functions
 
 
+def visit_latex_admonition(self) -> None:
+    self.body.append(LaTeX.visit_admonition())
+    # Write figures inside the box as [H] rather than floats, which LaTeX
+    # rejects there, as Sphinx does for its own admonitions
+    self.no_latex_floats += 1
+
+
+def depart_latex_admonition(self) -> None:
+    self.body.append(LaTeX.depart_admonition())
+    self.no_latex_floats -= 1
+
+
 def visit_exercise_node(self, node: Node) -> None:
     if isinstance(self, LaTeXTranslator):
         label = (
             "\\phantomsection \\label{" + f"exercise:{node.attributes['label']}" + "}"
         )  # TODO: Check this resolves.
         self.body.append(label)
-        self.body.append(LaTeX.visit_admonition())
+        visit_latex_admonition(self)
     else:
         self.body.append(self.starttag(node, "div", CLASS="admonition"))
         self.body.append("\n")
@@ -124,7 +136,7 @@ def visit_exercise_node(self, node: Node) -> None:
 
 def depart_exercise_node(self, node: Node) -> None:
     if isinstance(self, LaTeXTranslator):
-        self.body.append(LaTeX.depart_admonition())
+        depart_latex_admonition(self)
     else:
         self.body.append("</div>")
 
@@ -139,7 +151,7 @@ def visit_exercise_enumerable_node(self, node: Node) -> None:
             "\\phantomsection \\label{" + f"exercise:{node.attributes['label']}" + "}\n"
         )
         self.body.append(label)
-        self.body.append(LaTeX.visit_admonition())
+        visit_latex_admonition(self)
     else:
         self.body.append(self.starttag(node, "div", CLASS="admonition"))
         self.body.append("\n")
@@ -147,7 +159,7 @@ def visit_exercise_enumerable_node(self, node: Node) -> None:
 
 def depart_exercise_enumerable_node(self, node: Node) -> None:
     if isinstance(self, LaTeXTranslator):
-        self.body.append(LaTeX.depart_admonition())
+        depart_latex_admonition(self)
     else:
         self.body.append("</div>")
         self.body.append("\n")
@@ -167,7 +179,7 @@ def visit_solution_node(self, node: Node) -> None:
             + "}\n"
         )
         self.body.append(label)
-        self.body.append(LaTeX.visit_admonition())
+        visit_latex_admonition(self)
     else:
         self.body.append(self.starttag(node, "div", CLASS="admonition"))
         self.body.append("\n")
@@ -175,7 +187,7 @@ def visit_solution_node(self, node: Node) -> None:
 
 def depart_solution_node(self, node: Node) -> None:
     if isinstance(self, LaTeXTranslator):
-        self.body.append(LaTeX.depart_admonition())
+        depart_latex_admonition(self)
     else:
         self.body.append("</div>")
         self.body.append("\n")

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/sphinx_exercise/post_transforms.py

@@ -66,7 +66,8 @@ class UpdateReferencesToEnumerated(SphinxPostTransform):
                         # Get Metadata from Inline
                         inline = node.children[0]
                         classes = inline["classes"]
-                        classes.remove("std-ref")
+                        if "std-ref" in classes:
+                            classes.remove("std-ref")
                         classes.append("std-numref")
                         # Construct a Literal Node
                         literal = docutil_nodes.literal()

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/tests/books/test-gateddirective/conf.py

@@ -48,7 +48,11 @@ exclude_patterns = [
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_book_theme"
+# Use the built-in alabaster theme, as the other HTML test roots do.
+# The regression fixtures only capture the exercise/solution markup this
+# extension generates, so no third-party theme is needed to exercise them,
+# and depending on one couples the suite to that theme's Sphinx support.
+html_theme = "alabaster"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

sphinx_exercise-1.2.2/tests/books/test-latexfigure/conf.py

@@ -0,0 +1,11 @@
+# Test root for captioned figures inside exercise and solution boxes in
+# LaTeX output (https://github.com/executablebooks/sphinx-exercise/issues/94)
+
+project = "sphinx-exercise Test"
+copyright = "2020, QuantEcon Developers"
+author = "QuantEcon Developers"
+
+extensions = ["sphinx_exercise", "myst_nb"]
+
+# notebook.ipynb stores its outputs, so the test does not need a kernel
+nb_execution_mode = "off"

sphinx_exercise-1.2.2/tests/books/test-latexfigure/index.rst

@@ -0,0 +1,57 @@
+Figures in exercise and solution boxes
+======================================
+
+.. exercise:: A numbered exercise
+   :label: ex-numbered
+
+   .. figure:: plot.png
+      :name: fig-numbered-exercise
+
+      Figure in a numbered exercise
+
+.. exercise:: An unnumbered exercise
+   :label: ex-nonumber
+   :nonumber:
+
+   .. figure:: plot.png
+      :name: fig-unnumbered-exercise
+
+      Figure in an unnumbered exercise
+
+.. solution:: ex-numbered
+   :label: sol-numbered
+
+   .. figure:: plot.png
+      :name: fig-solution
+
+      Figure in a solution
+
+.. exercise-start:: A gated exercise
+   :label: ex-gated
+
+.. figure:: plot.png
+   :name: fig-gated-exercise
+
+   Figure in a gated exercise
+
+.. exercise-end::
+
+.. solution-start:: ex-gated
+   :label: sol-gated
+
+.. figure:: plot.png
+   :name: fig-gated-solution
+
+   Figure in a gated solution
+
+.. solution-end::
+
+.. figure:: plot.png
+   :name: fig-outside
+
+   Figure outside any box
+
+.. toctree::
+   :hidden:
+
+   notebook

sphinx_exercise-1.2.2/tests/books/test-latexfigure/notebook.ipynb

@@ -0,0 +1,85 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cell-0",
+   "metadata": {},
+   "source": [
+    "# Figures from code cells"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-1",
+   "metadata": {},
+   "source": [
+    "```{exercise} A notebook exercise\n",
+    ":label: ex-notebook\n",
+    "\n",
+    "Plot a line.\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-2",
+   "metadata": {},
+   "source": [
+    "```{solution-start} ex-notebook\n",
+    ":label: sol-notebook\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "cell-3",
+   "metadata": {
+    "mystnb": {
+     "figure": {
+      "caption": "Figure in a code-cell output",
+      "name": "fig-code-cell"
+     }
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAAAAADhZOFXAAAADklEQVR42mNogAIGyhgAgIQgARDoahcAAAAASUVORK5CYII=",
+      "text/plain": [
+       "<Figure size 640x480 with 1 Axes>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "plt.plot([0, 1], [0, 1]);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-4",
+   "metadata": {},
+   "source": [
+    "```{solution-end}\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{sphinx_exercise-1.2.0 → sphinx_exercise-1.2.2}/tests/conftest.py

@@ -99,6 +99,15 @@ class FileRegression:
         (r"ipykernel_\d+", "ipykernel_XXXXX"),
         # Normalize matplotlib image hashes (platform/version dependent)
         (r"[a-f0-9]{64}\.png", "IMAGEHASH.png"),
+        # Strip matplotlib font cache warning (appears in CI on first run)
+        (
+            r'<div class="output stderr highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>Matplotlib is building the font cache; this may take a moment\.\n</pre></div>\n</div>\n',
+            "",
+        ),
+        (
+            r'<literal_block classes="output stderr" language="myst-ansi" xml:space="preserve">\s*Matplotlib is building the font cache; this may take a moment\.\n\s*',
+            "",
+        ),
     )
 
     def __init__(self, file_regression):

sphinx_exercise-1.2.2/tests/test_latex.py

@@ -0,0 +1,71 @@
+import re
+
+from TexSoup import TexSoup
+import pytest
+import sphinx
+
+# Sphinx 8.1.x (Python 3.10 only) has different XML output than 8.2+
+# Use .sphinx8.1 for 8.1.x, .sphinx8 for 8.2+ (the standard)
+if sphinx.version_info[0] == 8 and sphinx.version_info[1] == 1:
+    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}.{sphinx.version_info[1]}"
+else:
+    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}"
+
+
+@pytest.mark.sphinx("latex", testroot="simplebook")
+def test_latex_build(app, file_regression):
+    app.build()
+    path_exer_directive = app.outdir / "sphinx-exercisetest.tex"
+    assert path_exer_directive.exists()
+
+    # get content markup
+    file_content = TexSoup(path_exer_directive.read_text(encoding="utf8"))
+    file_regression.check(
+        str(file_content.document), extension=f"{SPHINX_VERSION}.tex", encoding="utf8"
+    )
+
+
+LATEX_FIGURE = re.compile(
+    r"\\begin\{figure\}\[(?P<align>[^\]]*)\](?P<body>.*?)\\end\{figure\}", re.DOTALL
+)
+# A figure's :name: becomes \label{\detokenize{<docname>:<name>}}
+LATEX_FIGURE_NAME = re.compile(r"\\label\{\\detokenize\{[^:}]*:(?P<name>[^}]+)\}\}")
+
+
+def latex_figures(tex):
+    """Map each figure's name to (figure placement, sphinxadmonition depth).
+
+    A figure without a name is collected under None.
+    """
+    figures = {}
+    for figure in LATEX_FIGURE.finditer(tex):
+        before = tex[: figure.start()]
+        depth = before.count(r"\begin{sphinxadmonition}") - before.count(
+            r"\end{sphinxadmonition}"
+        )
+        name = LATEX_FIGURE_NAME.search(figure["body"])
+        figures[name["name"] if name else None] = (figure["align"], depth)
+    return figures
+
+
+@pytest.mark.sphinx("latex", testroot="latexfigure")
+def test_latex_figure_in_admonition(app):
+    """Figures inside exercise and solution boxes must not float (#94).
+
+    A floating figure environment inside the sphinxadmonition box stops
+    LaTeX with "Not in outer par mode".
+    """
+    app.build()
+    tex = (app.outdir / "sphinx-exercisetest.tex").read_text(encoding="utf8")
+
+    assert latex_figures(tex) == {
+        "fig-numbered-exercise": ("H", 1),
+        "fig-unnumbered-exercise": ("H", 1),
+        "fig-solution": ("H", 1),
+        "fig-gated-exercise": ("H", 1),
+        "fig-gated-solution": ("H", 1),
+        # Figures after the boxes float again, so the counter was restored
+        "fig-outside": ("htbp", 0),
+        # A code-cell output with mystnb figure metadata in a gated solution
+        "fig-code-cell": ("H", 1),
+    }

sphinx_exercise-1.2.0/tests/test_latex.py

@@ -1,23 +0,0 @@
-from TexSoup import TexSoup
-import pytest
-import sphinx
-
-# Sphinx 8.1.x (Python 3.10 only) has different XML output than 8.2+
-# Use .sphinx8.1 for 8.1.x, .sphinx8 for 8.2+ (the standard)
-if sphinx.version_info[0] == 8 and sphinx.version_info[1] == 1:
-    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}.{sphinx.version_info[1]}"
-else:
-    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}"
-
-
-@pytest.mark.sphinx("latex", testroot="simplebook")
-def test_latex_build(app, file_regression):
-    app.build()
-    path_exer_directive = app.outdir / "sphinx-exercisetest.tex"
-    assert path_exer_directive.exists()
-
-    # get content markup
-    file_content = TexSoup(path_exer_directive.read_text(encoding="utf8"))
-    file_regression.check(
-        str(file_content.document), extension=f"{SPHINX_VERSION}.tex", encoding="utf8"
-    )