texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/adapters/handlers/admonitions.py

@@ -0,0 +1,267 @@
+"""Handlers for generic admonition and callout markup."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import re
+
+from bs4.element import NavigableString, Tag
+
+from texsmith.core.callouts import DEFAULT_CALLOUTS
+from texsmith.core.context import RenderContext
+from texsmith.core.diagnostics import DiagnosticEmitter
+from texsmith.core.rules import RenderPhase, renders
+
+from ._helpers import gather_classes, mark_processed
+from .code import (
+    render_code_blocks as _render_code_block,
+    render_preformatted_code as _render_preformatted_code,
+    render_standalone_code_blocks as _render_standalone_code_block,
+)
+from .inline import render_inline_code as _render_inline_code
+
+
+IGNORED_CLASSES = {
+    "admonition",
+    "annotate",
+    "inline",
+    "end",
+    "left",
+    "right",
+    "checkbox",
+}
+
+
+def _trim_paragraph_prefix(paragraph: Tag, length: int) -> None:
+    """Remove the first ``length`` characters from a paragraph in-place."""
+    remaining = length
+    for node in list(paragraph.descendants):
+        if not isinstance(node, NavigableString):
+            continue
+        text = str(node)
+        if remaining >= len(text):
+            remaining -= len(text)
+            node.extract()
+            if remaining == 0:
+                break
+            continue
+        node.replace_with(NavigableString(text[remaining:]))
+        remaining = 0
+        break
+
+
+@contextmanager
+def _use_tcolorbox_figures(context: RenderContext):
+    """Render nested figures inside callouts with the tcolorbox template."""
+    previous = context.runtime.get("figure_template")
+    context.runtime["figure_template"] = "figure_tcolorbox"
+    try:
+        yield
+    finally:
+        if previous is None:
+            context.runtime.pop("figure_template", None)
+        else:
+            context.runtime["figure_template"] = previous
+
+
+def _extract_title(node: Tag | None) -> str:
+    """Extract and remove the title paragraph produced by MkDocs Material."""
+    if node is None:
+        return ""
+    if label := node.find("span", class_="exercise-label"):
+        label.decompose()
+    title = node.get_text(strip=True)
+    node.decompose()
+    return title
+
+
+CALLOUT_ALIASES = {"seealso": "info"}
+DEFAULT_CALLOUT_SET = set(DEFAULT_CALLOUTS)
+
+
+def _runtime_emitter(context: RenderContext) -> DiagnosticEmitter | None:
+    emitter = context.runtime.get("emitter")
+    return emitter if getattr(emitter, "warning", None) else None
+
+
+def _prepare_callout_content(element: Tag, context: RenderContext) -> None:
+    """Normalise inline and block code inside callouts before flattening."""
+    for highlight in list(element.find_all("div")):
+        highlight_classes = gather_classes(highlight.get("class"))
+        if "highlight" in highlight_classes or "codehilite" in highlight_classes:
+            _render_code_block(highlight, context)
+
+    for pre in list(element.find_all("pre")):
+        _render_preformatted_code(pre, context)
+
+    for code_block in list(element.find_all("code")):
+        _render_standalone_code_block(code_block, context)
+
+    for code in list(element.find_all("code")):
+        if code.find_parent("pre"):
+            continue
+        _render_inline_code(code, context)
+
+
+def _promote_callout(
+    element: Tag, context: RenderContext, *, classes: list[str], title: str
+) -> None:
+    """Re-tag a node so it can be converted after its children render."""
+    element["data-callout-title"] = title
+    element["class"] = classes
+    element.name = "texsmith-callout"
+    _prepare_callout_content(element, context)
+    element.attrs["data-callout-prepared"] = True
+    context.mark_processed(element, phase=RenderPhase.POST)
+
+
+def _render_admonition(
+    element: Tag, context: RenderContext, *, classes: list[str], title: str
+) -> None:
+    """Convert a generic admonition container into a LaTeX callout."""
+    admonition_classes = [cls for cls in classes if cls not in IGNORED_CLASSES]
+    admonition_type = admonition_classes[0] if admonition_classes else "note"
+    admonition_type = CALLOUT_ALIASES.get(admonition_type, admonition_type)
+    callouts_definitions = context.runtime.get("callouts_definitions") or DEFAULT_CALLOUTS
+    if admonition_type not in callouts_definitions:
+        emitter = _runtime_emitter(context)
+        if emitter:
+            emitter.warning(f"Unknown callout/admonition type '{admonition_type}', using default.")
+        admonition_type = "default"
+
+    if not element.attrs.pop("data-callout-prepared", False):
+        _prepare_callout_content(element, context)
+
+    with _use_tcolorbox_figures(context):
+        content = element.get_text(strip=False).strip()
+
+    context.state.callouts_used = True
+    latex = context.formatter.callout(content, title=title, type=admonition_type)
+    parent = element.parent
+    replacement = mark_processed(NavigableString(latex))
+    if parent is None:
+        element.decompose()
+        context.document.append(replacement)
+    else:
+        element.replace_with(replacement)
+
+
+@renders(
+    "div",
+    phase=RenderPhase.POST,
+    priority=50,
+    name="admonitions",
+    nestable=True,
+    auto_mark=False,
+)
+def render_div_admonitions(element: Tag, context: RenderContext) -> None:
+    """Handle MkDocs Material admonition blocks."""
+    classes = gather_classes(element.get("class"))
+    if "admonition" not in classes:
+        return
+    if "exercise" in classes:
+        return
+
+    title = _extract_title(element.find("p", class_="admonition-title"))
+    _promote_callout(element, context, classes=classes, title=title)
+
+
+@renders(
+    "blockquote",
+    phase=RenderPhase.POST,
+    priority=15,
+    name="blockquote_callouts",
+    nestable=True,
+    auto_mark=False,
+)
+def render_blockquote_callouts(element: Tag, context: RenderContext) -> None:
+    """Handle Obsidian/Docusaurus style blockquote callouts."""
+    first_paragraph = element.find("p")
+    if first_paragraph is None:
+        return
+
+    first_text_node = next(
+        (child for child in first_paragraph.contents if isinstance(child, NavigableString)),
+        None,
+    )
+    if first_text_node is None:
+        return
+
+    raw_text = str(first_text_node)
+    stripped = raw_text.lstrip()
+    offset = len(raw_text) - len(stripped)
+    match = CALLOUT_PATTERN.match(stripped)
+    if not match:
+        return
+
+    callout_type = match.group("kind").lower()
+    remainder = match.group("content") or ""
+    remainder = remainder.lstrip()
+
+    first_text_node.replace_with(NavigableString(raw_text[:offset] + remainder))
+
+    lines_with_endings = remainder.splitlines(keepends=True)
+    lines = [line.strip() for line in remainder.splitlines() if line.strip()]
+    title = lines[0] if lines else callout_type.capitalize()
+
+    if len(lines_with_endings) > 1:
+        prefix_length = len(raw_text[:offset]) + len(lines_with_endings[0])
+        _trim_paragraph_prefix(first_paragraph, prefix_length)
+        first_text = next(
+            (child for child in first_paragraph.contents if isinstance(child, NavigableString)),
+            None,
+        )
+        if first_text is not None:
+            first_text.replace_with(NavigableString(str(first_text).lstrip()))
+    else:
+        first_paragraph.decompose()
+
+    classes = gather_classes(element.get("class"))
+    preserved = [cls for cls in classes if cls != "admonition"]
+    new_classes = ["admonition", callout_type]
+    for cls in preserved:
+        if cls not in new_classes:
+            new_classes.append(cls)
+    element["class"] = new_classes
+    _promote_callout(element, context, classes=new_classes, title=title)
+
+
+@renders(
+    "details",
+    phase=RenderPhase.POST,
+    priority=55,
+    name="details_admonitions",
+    nestable=True,
+    auto_mark=False,
+)
+def render_details_admonitions(element: Tag, context: RenderContext) -> None:
+    """Handle collapsible callouts converted from MkDocs Material's details blocks."""
+    classes = gather_classes(element.get("class"))
+    if "exercise" in classes:
+        return
+
+    title = ""
+    if summary := element.find("summary"):
+        title = summary.get_text(strip=True)
+        summary.decompose()
+
+    _promote_callout(element, context, classes=classes, title=title or "")
+
+
+@renders(
+    "texsmith-callout",
+    phase=RenderPhase.POST,
+    priority=140,
+    name="finalize_callouts",
+    nestable=False,
+    auto_mark=False,
+    after_children=True,
+)
+def render_texsmith_callouts(element: Tag, context: RenderContext) -> None:
+    """Convert promoted callout nodes once their children have rendered."""
+    classes = gather_classes(element.get("class"))
+    title = element.attrs.pop("data-callout-title", "")
+    _render_admonition(element, context, classes=classes, title=title)
+
+
+CALLOUT_PATTERN = re.compile(r"^\s*\[!(?P<kind>[A-Za-z0-9_-]+)\]\s*(?P<content>.*)$", re.DOTALL)

texsmith/adapters/handlers/basic.py

@@ -0,0 +1,228 @@
+"""Built-in baseline handlers used by the renderer."""
+
+from __future__ import annotations
+
+from bs4.element import NavigableString, Tag
+from slugify import slugify
+
+from texsmith.core.context import RenderContext
+from texsmith.core.rules import RenderPhase, renders
+from texsmith.fonts.scripts import render_moving_text
+
+from ._helpers import coerce_attribute, gather_classes, mark_processed
+
+
+UNWANTED_NODES: tuple[tuple[str, tuple[str, ...], str], ...] = (
+    ("html", (), "unwrap"),
+    ("head", (), "decompose"),
+    ("body", (), "unwrap"),
+    ("a", ("headerlink", "footnote-backref"), "extract"),
+    ("a", ("glightbox",), "unwrap"),
+    ("div", ("latex-ignore",), "extract"),
+    ("span", ("exercise-title",), "unwrap"),
+    ("div", ("exercise-checkbox",), "extract"),
+    ("figure", ("mermaid-figure",), "extract"),
+)
+
+
+def _merge_strip_rules(
+    context: RenderContext,
+) -> list[tuple[str, tuple[str, ...], str]]:
+    """Merge default strip rules with runtime overrides."""
+    rules: dict[tuple[str, tuple[str, ...]], str] = {
+        (tag, classes): mode for tag, classes, mode in UNWANTED_NODES
+    }
+
+    runtime_rules = context.runtime.get("strip_tags") or {}
+    if isinstance(runtime_rules, dict):
+        for tag_name, payload in runtime_rules.items():
+            if isinstance(payload, str):
+                mode = payload
+                classes: tuple[str, ...] = ()
+            elif isinstance(payload, dict):
+                mode = payload.get("mode", "unwrap")
+                classes_value = payload.get("classes", ())
+                if isinstance(classes_value, str):
+                    classes = (classes_value,)
+                else:
+                    classes = tuple(classes_value)
+            else:
+                continue
+            if mode not in {"unwrap", "extract", "decompose"}:
+                continue
+            rules[(tag_name, classes)] = mode
+
+    merged = [(tag, classes, rules[(tag, classes)]) for tag, classes in rules]
+    return merged
+
+
+@renders(phase=RenderPhase.PRE, auto_mark=False, name="discard_unwanted")
+def discard_unwanted(root: Tag, context: RenderContext) -> None:
+    """Discard or unwrap nodes that must not reach later phases."""
+    for tag_name, classes, mode in _merge_strip_rules(context):
+        class_filter = list(classes)
+        candidates = (
+            root.find_all(tag_name, class_=class_filter)
+            if class_filter
+            else root.find_all(tag_name)
+        )
+        for node in candidates:
+            if mode == "unwrap":
+                node.unwrap()
+            elif mode == "extract":
+                node.extract()
+            elif mode == "decompose":
+                node.decompose()
+
+
+@renders("hr", phase=RenderPhase.BLOCK, name="render_horizontal_rule")
+def render_horizontal_rule(element: Tag, context: RenderContext) -> None:
+    """Render ``<hr>`` nodes as LaTeX horizontal rules."""
+    latex = context.formatter.horizontal_rule()
+    element.replace_with(mark_processed(NavigableString(latex)))
+
+
+@renders("br", phase=RenderPhase.INLINE, name="line_breaks")
+def replace_line_breaks(element: Tag, _context: RenderContext) -> None:
+    """Convert ``<br>`` tags into explicit LaTeX line breaks."""
+    element.replace_with(mark_processed(NavigableString("\\")))
+
+
+@renders("ins", phase=RenderPhase.INLINE, name="inline_underline", after_children=True)
+def render_inline_underline(element: Tag, context: RenderContext) -> None:
+    """Render ``<ins>`` tags using the formatter."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.underline(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("span", phase=RenderPhase.INLINE, name="inline_smallcaps", auto_mark=False)
+def render_inline_smallcaps(element: Tag, context: RenderContext) -> None:
+    """Render ``<span class=\"texsmith-smallcaps\">`` nodes as small capitals."""
+    classes = gather_classes(element.get("class"))
+    if "texsmith-smallcaps" not in classes:
+        return
+    text = element.get_text(strip=False)
+    latex = context.formatter.smallcaps(text=text)
+    element.replace_with(NavigableString(latex))
+    context.mark_processed(element)
+
+
+@renders("strong", phase=RenderPhase.INLINE, name="inline_strong", after_children=True)
+def render_inline_strong(element: Tag, context: RenderContext) -> None:
+    """Render ``<strong>`` tags using bold template."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.strong(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("em", phase=RenderPhase.INLINE, name="inline_emphasis", after_children=True)
+def render_inline_emphasis(element: Tag, context: RenderContext) -> None:
+    """Render ``<em>`` tags using emphasis template."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.italic(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("del", phase=RenderPhase.INLINE, name="inline_deletion", after_children=True)
+def render_inline_deletion(element: Tag, context: RenderContext) -> None:
+    """Render ``<del>`` tags using strikethrough template."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.strikethrough(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("mark", phase=RenderPhase.INLINE, name="inline_mark", after_children=True)
+def render_inline_mark(element: Tag, context: RenderContext) -> None:
+    """Render ``<mark>`` tags using highlight template."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.highlight(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("sub", phase=RenderPhase.INLINE, name="inline_subscript", after_children=True)
+def render_inline_subscript(element: Tag, context: RenderContext) -> None:
+    """Render ``<sub>`` tags."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.subscript(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("sup", phase=RenderPhase.INLINE, name="inline_superscript", after_children=True)
+def render_inline_superscript(element: Tag, context: RenderContext) -> None:
+    """Render ``<sup>`` tags, skipping footnote references."""
+    if element.get("id"):
+        return
+
+    text = element.get_text(strip=False)
+    latex = context.formatter.superscript(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("q", phase=RenderPhase.INLINE, name="inline_quote", after_children=True)
+def render_inline_quote(element: Tag, context: RenderContext) -> None:
+    """Render inline quotations using \\enquote{}."""
+    text = element.get_text(strip=False)
+    latex = context.formatter.enquote(text=text)
+    element.replace_with(NavigableString(latex))
+
+
+@renders("div", phase=RenderPhase.BLOCK, name="grid_cards", auto_mark=False)
+def unwrap_grid_cards(element: Tag, _context: RenderContext) -> None:
+    """Unwrap ``div.grid-cards`` containers."""
+    classes = element.get("class") or []
+    if "grid-cards" in classes:
+        element.unwrap()
+
+
+@renders(
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    phase=RenderPhase.POST,
+    name="render_headings",
+)
+def render_headings(element: Tag, context: RenderContext) -> None:
+    """Convert HTML headings to LaTeX sectioning commands."""
+    # Drop anchor tags within headings
+    for anchor in element.find_all("a"):
+        anchor.unwrap()
+
+    drop_title = context.runtime.get("drop_title")
+    if drop_title:
+        context.runtime["drop_title"] = False
+        latex = context.formatter.pagestyle(text="plain")
+        element.replace_with(mark_processed(NavigableString(latex)))
+        return
+
+    raw_text = element.get_text(strip=False)
+    text = render_moving_text(
+        raw_text,
+        context,
+        legacy_accents=getattr(context.config, "legacy_latex_accents", False),
+        escape="\\" not in raw_text,
+        wrap_scripts=True,
+    )
+    plain_text = element.get_text(strip=True)
+    level = int(element.name[1:])
+    base_level = context.runtime.get("base_level", 0)
+    rendered_level = level + base_level - 1
+    ref = coerce_attribute(element.get("id"))
+    if not ref:
+        slug = slugify(plain_text, separator="-")
+        ref = slug or None
+    numbered = context.runtime.get("numbered", True)
+
+    latex = context.formatter.heading(
+        text=text,
+        level=rendered_level,
+        ref=ref,
+        numbered=numbered,
+    )
+
+    element.replace_with(mark_processed(NavigableString(latex)))
+
+    context.state.add_heading(level=rendered_level, text=plain_text, ref=ref)