Preparation for tikz support in plasma-plots

.github/workflows/ci_pipeline.yml

@@ -25,9 +25,19 @@ jobs:
       #   with:
       #     python-version: ${{ matrix.python-version }}
 
+      - name: Install LaTeX
+        run: |
+          # pdflatex with pgfplots: the tikzfigure backend, its tests and tutorials
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            texlive-latex-base texlive-latex-extra texlive-pictures \
+            texlive-fonts-recommended lmodern
+
       - name: Install python dependencies
         run: |
           python -m pip install --upgrade pip
+          # tikzfigure 0.4.0 is not on PyPI yet: install it from GitHub (drop once released)
+          pip install "tikzfigure[vis] @ git+https://github.com/max-models/tikzfigure@c290f43ac1deb4a4ed3b5b40919f10d3a6b53e8b"
           pip install ".[dev]"
 
       - name: Run tests
@@ -37,7 +47,5 @@ jobs:
 
       - name: Test tutorials
         run: |
-          # tutorial_07_tikz.ipynb requires pdflatex — skip it in CI
-          jupyter nbconvert --to notebook --execute \
-            $(ls tutorials/*.ipynb | grep -v tutorial_07_tikz) \
+          jupyter nbconvert --to notebook --execute tutorials/*.ipynb \
             --output-dir=/tmp --ExecutePreprocessor.timeout=300

.github/workflows/docs.yml

@@ -33,6 +33,8 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
+          # tikzfigure 0.4.0 is not on PyPI yet: install it from GitHub (drop once released)
+          pip install "tikzfigure[vis] @ git+https://github.com/max-models/tikzfigure@c290f43ac1deb4a4ed3b5b40919f10d3a6b53e8b"
           pip install ".[docs]"
 
       - name: Build Sphinx docs

.github/workflows/matplotlib-import.yml

@@ -19,5 +19,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      # tikzfigure 0.4.0 is not on PyPI yet: install it from GitHub (drop once released)
+      - run: python -m pip install "tikzfigure[vis] @ git+https://github.com/max-models/tikzfigure@c290f43ac1deb4a4ed3b5b40919f10d3a6b53e8b"
       - run: python -m pip install '.[test]' 'numpy<2' 'matplotlib==${{ matrix.matplotlib }}'
       - run: python -m pytest src/maxplotlib/tests/test_matplotlib_import.py src/maxplotlib/tests/test_matplotlib_import_extended.py

README.md

@@ -219,23 +219,29 @@ canvas.show(backend="tikzfigure")
 
 ![](README_files/figure-commonmark/cell-14-output-1.png)
 
-### Horizontal Subplots with TikZ Backend
+### Subplots and Meshes with the TikZ Backend
 
-The tikzfigure backend supports creating side-by-side subplots (1×n
-layouts):
+The tikzfigure backend draws the canvas with Matplotlib and converts the
+drawn figure into pgfplots axes, so every layout converts (rows, columns,
+grids, twin axes), with LaTeX text, legends and colorbars. Lines,
+markers, bars and text are pgfplots code; meshes and images are included
+as images:
 
 ``` python
 x = np.linspace(0, 2 * np.pi, 200)
-canvas, (ax1, ax2) = Canvas.subplots(ncols=2, width="10cm", ratio=0.3)
+canvas, (ax1, ax2) = Canvas.subplots(ncols=2, width="12cm", ratio=0.45)
 
-ax1.plot(x, np.sin(x), color="royalblue")
-ax1.set_title("sin(x)")
+ax1.plot(x, np.sin(x), color="royalblue", label="$\\sin x$")
+ax1.plot(x, np.cos(x), color="tomato", label="$\\cos x$")
+ax1.set_title("Lines")
+ax1.set_legend(True)
 
-ax2.plot(x, np.cos(x), color="tomato")
-ax2.set_title("cos(x)")
+xx, yy = np.meshgrid(x, x)
+ax2.pcolormesh(xx, yy, np.sin(xx) * np.cos(yy), cmap="RdBu_r")
+ax2.add_colorbar(label="$\\sin x \\cos y$")
+ax2.set_title("A mesh")
 
-canvas.suptitle("Trigonometric Functions")
-canvas.show(backend="tikzfigure")  # Generates LaTeX subfigures
+canvas.show(backend="tikzfigure")  # compiles with pdflatex
 ```
 
 <div id="fig-showcase-subplots">
@@ -248,9 +254,11 @@ Figure 2
 
 </div>
 
-**Note:** Only horizontal layouts (1×n) are currently supported with the
-tikzfigure backend. Vertical/grid layouts will raise
-`NotImplementedError`. See the tutorials for more examples.
+`canvas.render(backend="tikzfigure").savefig("figure.tikz")` writes the
+code for `\\input` in a LaTeX document, with the images next to it. Any
+Matplotlib figure converts the same way with
+`maxplotlib.backends.tikzfigure.figure_to_tikz(fig)`. See the tutorials
+for more examples.
 
 ### Terminal Backend with plotext
 

README.qmd

@@ -194,29 +194,37 @@ Or plot with the TikZ backend:
 canvas.show(backend="tikzfigure")
 ```
 
-### Horizontal Subplots with TikZ Backend
+### Subplots and Meshes with the TikZ Backend
 
-The tikzfigure backend supports creating side-by-side subplots (1×n layouts):
+The tikzfigure backend draws the canvas with Matplotlib and converts the drawn figure into
+pgfplots axes, so every layout converts (rows, columns, grids, twin axes), with LaTeX text,
+legends and colorbars. Lines, markers, bars and text are pgfplots code; meshes and images are
+included as images:
 
 ```{python}
 #| label: fig-showcase-subplots
 #| fig-width: 9
 #| fig-height: 6
 
 x = np.linspace(0, 2 * np.pi, 200)
-canvas, (ax1, ax2) = Canvas.subplots(ncols=2, width="10cm", ratio=0.3)
+canvas, (ax1, ax2) = Canvas.subplots(ncols=2, width="12cm", ratio=0.45)
 
-ax1.plot(x, np.sin(x), color="royalblue")
-ax1.set_title("sin(x)")
+ax1.plot(x, np.sin(x), color="royalblue", label="$\\sin x$")
+ax1.plot(x, np.cos(x), color="tomato", label="$\\cos x$")
+ax1.set_title("Lines")
+ax1.set_legend(True)
 
-ax2.plot(x, np.cos(x), color="tomato")
-ax2.set_title("cos(x)")
+xx, yy = np.meshgrid(x, x)
+ax2.pcolormesh(xx, yy, np.sin(xx) * np.cos(yy), cmap="RdBu_r")
+ax2.add_colorbar(label="$\\sin x \\cos y$")
+ax2.set_title("A mesh")
 
-canvas.suptitle("Trigonometric Functions")
-canvas.show(backend="tikzfigure")  # Generates LaTeX subfigures
+canvas.show(backend="tikzfigure")  # compiles with pdflatex
 ```
 
-**Note:** Only horizontal layouts (1×n) are currently supported with the tikzfigure backend. Vertical/grid layouts will raise `NotImplementedError`. See the tutorials for more examples.
+`canvas.render(backend="tikzfigure").savefig("figure.tikz")` writes the code for `\\input` in a
+LaTeX document, with the images next to it. Any Matplotlib figure converts the same way with
+`maxplotlib.backends.tikzfigure.figure_to_tikz(fig)`. See the tutorials for more examples.
 
 ### Terminal Backend with plotext
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maxplotlibx"
-version = "0.1.9"
+version = "0.2.0"
 description = "A reproducible plotting module with various backends and export options."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -19,7 +19,7 @@ dependencies = [
     "pint",
     "plotly",
     "plotext >= 6.0, < 7",
-    "tikzfigure[vis]>=0.3.0",
+    "tikzfigure[vis]>=0.4.0",
 ]
 [project.optional-dependencies]
 test = [

src/maxplotlib/backends/tikzfigure/__init__.py

@@ -0,0 +1,9 @@
+"""The tikzfigure backend: pgfplots figures from what Matplotlib draws.
+
+See :func:`figure_to_tikz`; ``Canvas.render(backend="tikzfigure")`` uses it.
+"""
+
+from .convert import TikzConversionWarning, figure_to_tikz
+from .text import latex
+
+__all__ = ["TikzConversionWarning", "figure_to_tikz", "latex"]