feat: Improve error reporting with debug mode and chained exception support

- Add current_exception() method to Report class that supports
  debug mode (full traceback when debug=True)
- Enhance exception() to show chained exceptions with "Caused by:" messages
- Use current_exception() in pending_node.resolve() for better
  error diagnostics
- Pass debug=self.template.debug to error reports for template
  rendering failures

Co-authored-by: DeepSeek <service@deepseek.com>

Author: SilverRainZ

src/sphinxnotes/render/ctxnodes.py

@@ -95,10 +95,13 @@ def err_report() -> Report:
 
         if self._ctx_pickle_error is not None:
             report = err_report()
-            report.exception(self._ctx_pickle_error, caption=(
-                f'UnresolvedContext used by {self.template.phase} phase templates '
-                'must be picklable:'
-            ))
+            report.exception(
+                self._ctx_pickle_error,
+                caption=(
+                    f'UnresolvedContext used by {self.template.phase} phase templates '
+                    'must be picklable:'
+                ),
+            )
             self += report
             return None
 
@@ -112,9 +115,12 @@ def err_report() -> Report:
 
             try:
                 ctx = self.ctx = pdata.resolve(host.env)
-            except Exception as e:
+            except Exception:
                 report = err_report()
-                report.exception(e, caption='Failed to resolve unresolved context:')
+                report.current_exception(
+                    caption='Failed to resolve unresolved context:',
+                    debug=self.template.debug,
+                )
                 self += report
                 return None
         else:
@@ -123,11 +129,23 @@ def err_report() -> Report:
         for hook in self._resolved_context_hooks:
             hook(self, ctx)
 
-        report.code(pformat(ctx), lang='python', caption=f'Resolved context (type: {type(ctx)}):')
-        report.code(self.template.text, lang='jinja', caption=f'Template (phase: {self.template.phase}):')
+        report.code(
+            pformat(ctx),
+            lang='python',
+            caption=f'Resolved context (type: {type(ctx)}):',
+        )
+        report.code(
+            self.template.text,
+            lang='jinja',
+            caption=f'Template (phase: {self.template.phase}):',
+        )
 
         extractx_req = ExtraContextRequest(self.template.phase, self, host.env, host)
-        report.code(pformat(sorted(extra_context_names())), lang='python', caption='Available extra context names:')
+        report.code(
+            pformat(sorted(extra_context_names())),
+            lang='python',
+            caption='Available extra context names:',
+        )
 
         # 2. Render the template and context to markup text.
         try:
@@ -136,9 +154,11 @@ def err_report() -> Report:
                 globals={'load_extra': extra_context_loader(extractx_req)},
                 debug=self.template.debug,
             )
-        except Exception as e:
+        except Exception:
             report = err_report()
-            report.exception(e, caption='Failed to render Jinja template:')
+            report.current_exception(
+                caption='Failed to render Jinja template:', debug=self.template.debug
+            )
             self += report
             return
 
@@ -150,16 +170,23 @@ def err_report() -> Report:
         # 3. Render the markup text to doctree nodes.
         try:
             ns, msgs = MarkupRenderer(host).render(markup, inline=self.inline)
-        except Exception as e:
+        except Exception:
             report = err_report()
-            report.exception(e, caption=(
-                'Failed to render markup text '
-                f'to {"inline " if self.inline else ""}nodes:'
-            ))
+            report.current_exception(
+                caption=(
+                    'Failed to render markup text '
+                    f'to {"inline " if self.inline else ""}nodes:'
+                ),
+                debug=self.template.debug,
+            )
             self += report
             return
 
-        report.code('\n\n'.join([n.pformat() for n in ns]), lang='xml', caption=f'Rendered nodes (inline: {self.inline}):')
+        report.code(
+            '\n\n'.join([n.pformat() for n in ns]),
+            lang='xml',
+            caption=f'Rendered nodes (inline: {self.inline}):',
+        )
         if msgs:
             report.text('Systemd messages:')
             [report.node(msg) for msg in msgs]

src/sphinxnotes/render/utils/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 from dataclasses import dataclass
+import sys
 from typing import TYPE_CHECKING, TypeVar, cast
 import traceback
 
@@ -123,13 +124,17 @@ def log(self, msg: str) -> None:
     def text(self, text: str) -> None:
         self.node(nodes.paragraph(text, text))
 
-    def code(self, code: str, lang: str | None = None, caption: str | None = None) -> None:
+    def code(
+        self, code: str, lang: str | None = None, caption: str | None = None
+    ) -> None:
         blk = nodes.literal_block(code, code)
         if lang:
             blk['language'] = lang
         if caption:
             # See also: :meth:`sphinx.directives.code.container_wrapper`.
-            container = nodes.container('', literal_block=True, classes=['literal-block-wrapper'])
+            container = nodes.container(
+                '', literal_block=True, classes=['literal-block-wrapper']
+            )
             container += nodes.caption(caption, '', nodes.Text(caption))
             container += blk
             self.node(container)
@@ -152,9 +157,35 @@ def traceback(self, caption: str | None = None) -> None:
         # https://pygments.org/docs/lexers/#pygments.lexers.python.PythonTracebackLexer
         self.code(traceback.format_exc(), lang='pytb', caption=caption)
 
-    def exception(self, e: Exception, caption: str | None = None) -> None:
+    def exception(
+        self, e: Exception | BaseException, caption: str | None = None
+    ) -> None:
+        # A simplifed traceback.
+        msg, cause, depth = str(e), e.__cause__, 1
+        logger.warning('frist: %s', e.__cause__)
+        while cause:
+            msg += (
+                '\n\n'
+                + (depth - 1) * 2 * ' '
+                + 'Caused by:\n'
+                + depth * 2 * ' '
+                + str(cause)
+            )
+            cause = cause.__cause__
+            logger.warning('frist: %s', cause)
         # https://pygments.org/docs/lexers/#pygments.lexers.python.PythonTracebackLexer
-        self.code(str(e), lang='pytb', caption=caption)
+        self.code(msg, lang='pytb', caption=caption)
+
+    def current_exception(
+        self, caption: str | None = None, debug: bool = False
+    ) -> None:
+        if debug:
+            self.traceback(caption=caption)
+            return
+        _, e, _ = sys.exc_info()
+        if e is None:
+            return
+        self.exception(e, caption=caption)
 
     def is_error(self) -> bool:
         return self['type'] == 'ERROR'