Display typst compile errors to the user in a friendly way

src/atsphinx/typst/builders.py

@@ -75,9 +75,9 @@ def write_doc(self, document_settings: DocumentSettings):  # noqa: D102
         visitor: writer.TypstTranslator = self.create_translator(doctree, self)  # type: ignore[assignment]
         doctree.walkabout(visitor)
         context = theming.ThemeContext(
-            project=self.app.config.project,
-            release=self.app.config.release,
-            copyright=self.app.config.copyright,
+            project=self.config.project,
+            release=self.config.release,
+            copyright=self.config.copyright,
             # TODO: Support user custm format.
             build_date=self._build_date.strftime("%Y-%m-%d"),
             title=document_settings["title"],
@@ -88,7 +88,7 @@ def write_doc(self, document_settings: DocumentSettings):  # noqa: D102
             packages=visitor.packages,
             translated=visitor.context,
         )
-        out = Path(self.app.outdir) / f"{document_settings['filename']}.typ"
+        out = Path(self.outdir) / f"{document_settings['filename']}.typ"
         theme.write_doc(out, context)
 
     def assemble_doctree(
@@ -122,7 +122,7 @@ def get_target_uri(self, docname, typ=None):  # noqa: D102
     def copy_assets(self):  # noqa: D102
         # Copying all theme assets.
         def _copy_theme_assets():
-            base_dir = self.app.outdir / "_themes"
+            base_dir = self.outdir / "_themes"
             for name, theme in self._themes.items():
                 assets_outdir = base_dir / name
                 assets_srcdir = theme.get_theme_dir() / "assets"
@@ -178,6 +178,9 @@ def finish(self):  # noqa: D102
         if self.config.typst_font_paths:
             kwargs["font_paths"] = self.config.typst_font_paths
         for document_settings in self.config.typst_documents:
-            src = Path(self.app.outdir) / f"{document_settings['filename']}.typ"
-            out = Path(self.app.outdir) / f"{document_settings['filename']}.pdf"
-            typst.compile(src, output=out, **kwargs)
+            src = Path(self.outdir) / f"{document_settings['filename']}.typ"
+            out = Path(self.outdir) / f"{document_settings['filename']}.pdf"
+            try:
+                typst.compile(src, output=out, **kwargs)
+            except typst.TypstError as e:
+                raise SphinxError(f"Typst compilation failed for {str(src)!r}: {e.diagnostic}") from e

src/atsphinx/typst/writer.py

@@ -92,7 +92,7 @@ def visit_image(self, node: nodes.image):
         source = Path(self.document["source"])
         uri_path = source.parent / uri
         uri_dest = self.builder._images_dir / uri_path.relative_to(
-            self.builder.app.srcdir
+            self.builder.srcdir
         )
         uri_map = uri_dest.relative_to(self.builder.outdir)
         self.builder.images.setdefault(uri_path, uri_dest)

tests/test_builders.py

@@ -80,3 +80,15 @@ def test__document_font(self, app: SphinxTestApp):
             app.build()
             assert (app.outdir / "index.typ").exists()
             assert (app.outdir / "index.pdf").exists()
+
+    class Test_compile_error:
+        @pytest.mark.sphinx("typstpdf", testroot="typst-compile-error")
+        def test__typst_compile_error_handling(self, app: SphinxTestApp):
+            """Test that TypstError is caught and rethrown with diagnostics."""
+            from sphinx.errors import SphinxError
+
+            with pytest.raises(SphinxError, match="unclosed delimiter"):
+                app.build()
+
+            # Verify PDF was not created due to compilation failure.
+            assert not (app.outdir / "index.pdf").exists()

tests/testdocs/test-typst-compile-error/conf.py

@@ -0,0 +1,14 @@
+# noqa: D100
+
+extensions = [
+    "atsphinx.typst",
+]
+
+typst_documents = [
+    {
+        "entrypoint": "index",
+        "filename": "index",
+        "theme": "manual",
+        "title": "Test documentation with compile error",
+    }
+]

tests/testdocs/test-typst-compile-error/index.rst

@@ -0,0 +1,8 @@
+Test doc with Typst compile error
+==================================
+
+This document contains invalid Typst syntax that will cause a compile error.
+
+.. raw:: typst
+
+   #let unclosed = [