mdmint 0.2.0__py3-none-any.whl

mdmint/mathrender.py

@@ -0,0 +1,114 @@
+"""LaTeX math rendering — optional, with graceful fallback.
+
+Static output formats (PDF/DOCX) cannot run MathJax, so math has to become an
+image. If ``matplotlib`` is installed we render each expression with its built-in
+``mathtext`` engine (a sizeable LaTeX-math subset, no system LaTeX required) to a
+transparent PNG. If matplotlib is absent, or an expression isn't supported, we fall
+back to the literal source text and warn once.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import logging
+import os
+from pathlib import Path
+from types import ModuleType
+from typing import Literal
+
+log = logging.getLogger("mdmint")
+
+_DPI = 200  # render resolution; combined with pixel size to derive on-page pt size
+_MATPLOTLIB: ModuleType | Literal[False] | None = None  # None = not probed yet
+_WARNED = False
+_cache: dict[str, str] = {}
+
+
+def _get_matplotlib() -> ModuleType | None:
+    global _MATPLOTLIB
+    if _MATPLOTLIB is None:
+        try:
+            import matplotlib
+
+            matplotlib.use("Agg")  # headless backend, no display needed
+            _MATPLOTLIB = matplotlib
+        except Exception:  # pragma: no cover - depends on environment
+            _MATPLOTLIB = False
+    return _MATPLOTLIB or None
+
+
+def _warn_missing() -> None:
+    global _WARNED
+    if not _WARNED:
+        log.warning(
+            "math: matplotlib not installed; rendering math as literal text. "
+            "Install with 'pip install mdmint[math]' for rendered equations."
+        )
+        _WARNED = True
+
+
+def _fallback(expr: str, block: bool) -> str:
+    escaped = html.escape(expr)
+    if block:
+        return f'<p class="math-block-fallback"><code>$$ {escaped} $$</code></p>'
+    return f'<code class="math-inline-fallback">${escaped}$</code>'
+
+
+def render(expr: str, block: bool, work_dir: Path) -> str:
+    """Return an HTML snippet (an ``<img>`` or literal fallback) for one expression."""
+    mpl = _get_matplotlib()
+    if mpl is None:
+        _warn_missing()
+        return _fallback(expr, block)
+
+    key = ("B:" if block else "I:") + expr
+    if key in _cache:
+        return _cache[key]
+
+    digest = hashlib.sha1(key.encode("utf-8"), usedforsecurity=False).hexdigest()[:16]
+    out_path = work_dir / f"math-{digest}.png"
+
+    try:
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+        from matplotlib.figure import Figure
+
+        fig = Figure(figsize=(0.1, 0.1))
+        FigureCanvasAgg(fig)
+        # mathtext expects the expression wrapped in $...$.
+        fig.text(0, 0, f"${expr}$", fontsize=14)
+        fig.savefig(
+            out_path,
+            dpi=_DPI,
+            format="png",
+            bbox_inches="tight",
+            pad_inches=0.02,
+            transparent=True,
+        )
+
+        # Derive on-page size in points so the image matches surrounding text.
+        from PIL import Image  # Pillow ships as a matplotlib dependency
+
+        with Image.open(out_path) as im:
+            w_px, h_px = im.size
+        h_pt = h_px / _DPI * 72.0
+        w_pt = w_px / _DPI * 72.0
+    except Exception as exc:
+        log.warning("math: could not render %r (%s); using literal text.", expr, type(exc).__name__)
+        result = _fallback(expr, block)
+        _cache[key] = result
+        return result
+
+    src = html.escape(os.path.abspath(out_path))
+    if block:
+        snippet = (
+            f'<p class="math-block"><img class="math-block" src="{src}" '
+            f'alt="{html.escape(expr)}" style="height:{h_pt:.1f}pt" /></p>'
+        )
+    else:
+        snippet = (
+            f'<img class="math-inline" src="{src}" alt="{html.escape(expr)}" '
+            f'style="height:{h_pt:.1f}pt;width:{w_pt:.1f}pt" />'
+        )
+    _cache[key] = snippet
+    return snippet

mdmint/mermaid.py

@@ -0,0 +1,149 @@
+"""Mermaid diagram rendering — optional, with graceful fallback.
+
+There is no pure-Python Mermaid renderer. If the mermaid CLI (``mmdc``, from
+``@mermaid-js/mermaid-cli``) happens to be installed and on PATH, we shell out to
+it and embed the resulting image. Otherwise we emit the diagram source as a styled
+code block and warn once. ``mmdc`` is never required to install or use mdmint.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import logging
+import os
+import shutil
+import struct
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+log = logging.getLogger("mdmint")
+
+# Cached result of the PATH lookup (False once we know it's absent).
+_MMDC_PATH: str | Literal[False] | None = None
+_WARNED = False
+
+# mmdc emits PNGs at CSS-pixel dimensions; place them on the page treating those
+# pixels as 96 DPI (xhtml2pdf's default image DPI).
+_PNG_DPI = 96.0
+# Cap diagram width to the printable page width so wide diagrams don't overflow the
+# margin. A4 (210mm) minus the 2cm side margins set in resources/default.css.
+_MAX_WIDTH_PT = (210.0 - 2 * 20.0) / 25.4 * 72.0  # ~481.9pt
+
+
+def _find_mmdc() -> str | None:
+    """Locate the mermaid CLI on PATH, caching the result for the process."""
+    global _MMDC_PATH
+    if _MMDC_PATH is None:
+        # On Windows the executable is usually ``mmdc.cmd``; shutil.which handles
+        # the extension resolution via PATHEXT.
+        _MMDC_PATH = shutil.which("mmdc") or False
+    return _MMDC_PATH or None
+
+
+def is_snap_confined() -> bool:
+    """True if the available mmdc is a snap package.
+
+    Snap strict confinement cannot read ``/tmp`` or hidden dot-directories, so when
+    rendering with a snap mmdc the work directory must live in a non-hidden path
+    under the user's home (handled by :func:`mdmint.core._make_work_dir`).
+    """
+    mmdc = _find_mmdc()
+    return bool(mmdc and "/snap/" in mmdc.replace("\\", "/"))
+
+
+def _codeblock(source: str) -> str:
+    """Render the diagram source as a styled, escaped code block (no logging)."""
+    return f'<pre class="mermaid"><code>{html.escape(source)}</code></pre>'
+
+
+def _png_size_pt(path: Path) -> tuple[float, float] | None:
+    """Return a rendered PNG's on-page (width, height) in points, capped to the page
+    width and preserving aspect ratio. ``None`` if the size can't be read.
+
+    Reads the dimensions straight from the PNG IHDR header (no image library), so it
+    works in the pure-Python core install.
+    """
+    try:
+        with open(path, "rb") as fh:
+            header = fh.read(24)
+    except OSError:
+        return None
+    if len(header) < 24 or header[:8] != b"\x89PNG\r\n\x1a\n":
+        return None
+    w_px, h_px = struct.unpack(">II", header[16:24])
+    if not w_px or not h_px:
+        return None
+    w_pt = w_px * 72.0 / _PNG_DPI
+    h_pt = h_px * 72.0 / _PNG_DPI
+    if w_pt > _MAX_WIDTH_PT:  # scale down to fit; never upscale small diagrams
+        h_pt *= _MAX_WIDTH_PT / w_pt
+        w_pt = _MAX_WIDTH_PT
+    return w_pt, h_pt
+
+
+def _warn_once(message: str) -> None:
+    global _WARNED
+    if not _WARNED:
+        log.warning(message)
+        _WARNED = True
+
+
+def render(source: str, work_dir: Path) -> str:
+    """Return an HTML snippet for a single mermaid diagram.
+
+    If ``mmdc`` is available, render ``source`` to a PNG inside ``work_dir`` and
+    return an ``<img>`` tag pointing at the absolute path. Otherwise fall back to a
+    code block. Rendering failures also fall back, so a bad diagram never aborts the
+    whole conversion.
+    """
+    mmdc = _find_mmdc()
+    if not mmdc:
+        _warn_once(
+            "mermaid: no local renderer found (mmdc not on PATH); rendering "
+            "diagrams as code blocks. Install '@mermaid-js/mermaid-cli' for real "
+            "diagrams."
+        )
+        return _codeblock(source)
+
+    digest = hashlib.sha1(source.encode("utf-8"), usedforsecurity=False).hexdigest()[:16]
+    out_path = work_dir / f"mermaid-{digest}.png"
+
+    if not out_path.exists():
+        in_path = work_dir / f"mermaid-{digest}.mmd"
+        in_path.write_text(source, encoding="utf-8")
+        cmd = [
+            mmdc,
+            "-i",
+            str(in_path),
+            "-o",
+            str(out_path),
+            "-b",
+            "transparent",
+        ]
+        try:
+            subprocess.run(  # noqa: S603 - argv is the mmdc path and our own temp files
+                cmd,
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=60,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError) as exc:
+            detail = getattr(exc, "stderr", b"")
+            if isinstance(detail, bytes):
+                detail = detail.decode("utf-8", "replace")
+            _warn_once(
+                "mermaid: rendering failed (%s); falling back to code block. %s"
+                % (type(exc).__name__, detail.strip())
+            )
+            return _codeblock(source)
+
+    src = os.path.abspath(out_path)
+    size = _png_size_pt(out_path)
+    style = f' style="width:{size[0]:.1f}pt;height:{size[1]:.1f}pt"' if size else ""
+    return (
+        f'<p class="mermaid-diagram"><img src="{html.escape(src)}"{style} '
+        'alt="mermaid diagram" /></p>'
+    )

mdmint/mkdocs.py

@@ -0,0 +1,310 @@
+"""Build one document from an mkdocs project: its ``nav`` decides what goes in and
+in which order, and its section nesting decides the heading structure.
+
+Each page is rendered through the normal pipeline, then stitched together here:
+
+* **Sections** become headings. With ``section_style="part"`` (default) a
+  top-level section is a *part* divider (``<h1 class="part">``) that does not use
+  up a heading level, so its pages keep their own ``#`` as chapters; nested
+  sections become ``h1``, ``h2``… and demote their pages accordingly. With
+  ``section_style="heading"`` every section is a plain heading one level above
+  its pages.
+* **Appendices** — pages under a section titled *Annex(es)* / *Appendix* /
+  *Appendices* get their chapter heading marked ``class="appendix"``.
+* **Links** between pages (``../other/index.md#anchor``) are rewritten to
+  in-document anchors; links to pages left out of the nav are unwrapped to text.
+* **Ids** are namespaced per page (``p3-…``) so headings and footnotes from
+  different pages never collide.
+"""
+
+from __future__ import annotations
+
+import html
+import logging
+import os
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import unquote
+
+from . import render
+
+if TYPE_CHECKING:
+    import yaml
+
+log = logging.getLogger("mdmint")
+
+SECTION_STYLES = ("part", "heading")
+_APPENDIX_TITLE = re.compile(r"^\s*(annex(es)?|appendix|appendices)\b", re.IGNORECASE)
+_ANCHOR = re.compile(r'<a\b([^>]*?)\bhref="([^"]*)"([^>]*)>(.*?)</a>', re.DOTALL)
+_URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.IGNORECASE)
+# Keys of ``extra.mdmint`` that configure mdmint rather than fill template placeholders.
+_OPTION_KEYS = ("template", "section_style", "styles")
+
+
+@dataclass
+class NavEntry:
+    kind: str  # "section" or "page"
+    title: str | None
+    depth: int  # number of enclosing sections
+    path: Path | None = None  # pages only (absolute)
+    appendix: bool = False  # inside an annex/appendix section
+
+
+@dataclass
+class Project:
+    config_path: Path
+    docs_dir: Path
+    site_name: str
+    entries: list[NavEntry]
+    meta: dict[str, str] = field(default_factory=dict)
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+# ------------------------------------------------------------------ config
+
+
+def _yaml_loader() -> type[yaml.SafeLoader]:
+    """A SafeLoader that tolerates mkdocs' custom tags instead of failing on them.
+
+    mkdocs.yml routinely contains ``!!python/name:…`` (pymdownx fences) and
+    ``!ENV`` / ``!relative`` tags; we never need their values, only the nav.
+    """
+    import yaml
+
+    class Loader(yaml.SafeLoader):
+        pass
+
+    def plain(loader: yaml.SafeLoader, _suffix: str, node: yaml.Node) -> Any:
+        if isinstance(node, yaml.ScalarNode):
+            return loader.construct_scalar(node)
+        if isinstance(node, yaml.SequenceNode):
+            return loader.construct_sequence(node)
+        return loader.construct_mapping(cast("yaml.MappingNode", node))
+
+    Loader.add_multi_constructor("tag:yaml.org,2002:python/", lambda *a: None)
+    Loader.add_multi_constructor("!", plain)
+    return Loader
+
+
+def load(config_path: str | os.PathLike[str]) -> Project:
+    """Read an mkdocs.yml and resolve its nav into an ordered list of entries."""
+    import yaml
+
+    config_path = Path(config_path).resolve()
+    if not config_path.is_file():
+        raise FileNotFoundError(f"mkdocs config not found: {config_path}")
+    try:
+        text = config_path.read_text(encoding="utf-8")
+        cfg = yaml.load(text, Loader=_yaml_loader()) or {}  # noqa: S506 (a SafeLoader)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"{config_path}: invalid YAML — {exc}") from exc
+    if not isinstance(cfg, dict):
+        raise ValueError(f"{config_path}: expected a mapping at the top level")
+
+    docs_dir = (config_path.parent / (cfg.get("docs_dir") or "docs")).resolve()
+    if not docs_dir.is_dir():
+        raise FileNotFoundError(f"docs_dir not found: {docs_dir}")
+
+    entries: list[NavEntry] = []
+    if cfg.get("nav"):
+        _walk_nav(cfg["nav"], docs_dir, 0, False, entries)
+    else:
+        log.info("mkdocs: no nav in %s; using the docs_dir file tree", config_path.name)
+        _walk_tree(docs_dir, 0, entries)
+    if not any(e.kind == "page" for e in entries):
+        raise ValueError(f"{config_path}: nav contains no Markdown pages")
+
+    site_name = str(cfg.get("site_name") or config_path.parent.name)
+    extra = (cfg.get("extra") or {}).get("mdmint") or {}
+    if not isinstance(extra, dict):
+        extra = {}
+    meta = {"title": site_name}
+    if cfg.get("site_description"):
+        meta["subtitle"] = str(cfg["site_description"])
+    if cfg.get("site_author"):
+        meta["author"] = str(cfg["site_author"])
+    meta.update(
+        {
+            str(k).lower(): str(v)
+            for k, v in extra.items()
+            if k not in _OPTION_KEYS and v is not None
+        }
+    )
+    options = {k: extra[k] for k in _OPTION_KEYS if k in extra}
+    if "template" in options:
+        options["template"] = (config_path.parent / str(options["template"])).resolve()
+    return Project(config_path, docs_dir, site_name, entries, meta, options)
+
+
+def _walk_nav(items: Any, docs_dir: Path, depth: int, appendix: bool, out: list[NavEntry]) -> None:
+    if isinstance(items, (str, dict)):
+        items = [items]
+    for item in items or []:
+        if isinstance(item, str):
+            _add_page(None, item, docs_dir, depth, appendix, out)
+        elif isinstance(item, dict):
+            for title, value in item.items():
+                title = None if title is None else str(title)
+                if isinstance(value, list):
+                    in_appendix = appendix or bool(title and _APPENDIX_TITLE.match(title))
+                    section = NavEntry("section", title, depth, appendix=in_appendix)
+                    start = len(out)
+                    out.append(section)
+                    _walk_nav(value, docs_dir, depth + 1, in_appendix, out)
+                    if not any(e.kind == "page" for e in out[start + 1 :]):
+                        del out[start:]  # drop sections with nothing to show
+                elif isinstance(value, str):
+                    _add_page(title, value, docs_dir, depth, appendix, out)
+
+
+def _add_page(
+    title: str | None,
+    ref: str,
+    docs_dir: Path,
+    depth: int,
+    appendix: bool,
+    out: list[NavEntry],
+) -> None:
+    if _URL_SCHEME.match(ref) or ref.startswith("//"):
+        log.info("mkdocs: skipping external nav link %s", ref)
+        return
+    path = (docs_dir / ref).resolve()
+    if path.is_dir():
+        path = next((path / n for n in ("index.md", "README.md") if (path / n).is_file()), path)
+    if not path.is_file():
+        log.warning("mkdocs: nav entry not found, skipping: %s", ref)
+        return
+    if path.suffix.lower() not in (".md", ".markdown"):
+        log.info("mkdocs: skipping non-Markdown nav entry %s", ref)
+        return
+    out.append(NavEntry("page", title, depth, path, appendix))
+
+
+def _walk_tree(directory: Path, depth: int, out: list[NavEntry]) -> None:
+    """Implicit mkdocs nav: index/README first, then files and dirs by name."""
+
+    def key(p: Path) -> tuple[bool, str]:
+        return (p.stem.lower() not in ("index", "readme"), p.name.lower())
+
+    for child in sorted(directory.iterdir(), key=key):
+        if child.name.startswith("."):
+            continue
+        if child.is_dir():
+            title = child.name.replace("-", " ").replace("_", " ").strip().capitalize()
+            start = len(out)
+            out.append(NavEntry("section", title, depth))
+            _walk_tree(child, depth + 1, out)
+            if not any(e.kind == "page" for e in out[start + 1 :]):
+                del out[start:]
+        elif child.suffix.lower() in (".md", ".markdown"):
+            out.append(NavEntry("page", None, depth, child.resolve()))
+
+
+# ---------------------------------------------------------------- assembly
+
+
+def _levels(entry: NavEntry, section_style: str) -> int:
+    """Section: its heading level (0 = part). Page: how far to demote it."""
+    if section_style == "heading":
+        return entry.depth + 1 if entry.kind == "section" else entry.depth
+    if entry.kind == "section":
+        return entry.depth  # 0 → part divider, 1 → h1, …
+    return max(0, entry.depth - 1)
+
+
+def assemble(
+    project: Project, render_page: Callable[[Path], str], *, section_style: str = "part"
+) -> str:
+    """Render every nav page with ``render_page(path) -> html`` and join them.
+
+    Returns the combined HTML fragment (no TOC; the caller adds one if wanted).
+    """
+    if section_style not in SECTION_STYLES:
+        raise ValueError(f"Unknown section_style {section_style!r}; use one of {SECTION_STYLES}")
+
+    # Pass 1: render pages, namespace their ids, fix up heading levels.
+    prefixes: dict[Path, str] = {}
+    first_ids: dict[Path, str] = {}
+    blocks: list[tuple[Path | None, str]] = []  # (page path, None for a section; html)
+    for idx, entry in enumerate(project.entries):
+        if entry.kind == "section":
+            level = _levels(entry, section_style)
+            cls = ' class="part"' if level == 0 else ""
+            anchor = f"s{idx}-{render.slugify(entry.title or 'section')}"
+            label = html.escape(entry.title or "")
+            blocks.append(
+                (None, f'<h{max(level, 1)} id="{anchor}"{cls}>{label}</h{max(level, 1)}>\n')
+            )
+            continue
+
+        path = entry.path
+        if path is None:  # pragma: no cover - every page entry has a path
+            continue
+        prefix = f"p{idx}-"
+        prefixes.setdefault(path, prefix)
+        body = render_page(path)
+        if not re.search(r"<h1\b", body):
+            # No H1 of its own: use the nav title (or file name) as the page title.
+            title = entry.title or path.stem.replace("-", " ").replace("_", " ").capitalize()
+            body = f'<h1 id="{render.slugify(title)}">{html.escape(title)}</h1>\n' + body
+        body = render.namespace_ids(body, prefix)
+        offset = _levels(entry, section_style)
+        if entry.appendix and offset == 0:
+            body = _mark_first_h1(body, "appendix")
+        body = render.shift_headings(body, offset)
+        heads = render.headings_from_html(body)
+        first_id = heads[0][2] if heads else None
+        if first_id:
+            first_ids.setdefault(path, first_id)
+        blocks.append((path, body))
+
+    # Pass 2: rewrite links between pages now that every target id is known.
+    parts = []
+    for page, body in blocks:
+        if page is not None:
+            body = _rewrite_links(body, page, prefixes, first_ids)
+        parts.append(body)
+    return "\n".join(parts)
+
+
+def _mark_first_h1(body: str, cls: str) -> str:
+    def repl(m: re.Match[str]) -> str:
+        attrs = m.group(1)
+        if 'class="' in attrs:
+            attrs = attrs.replace('class="', f'class="{cls} ', 1)
+        else:
+            attrs += f' class="{cls}"'
+        return f"<h1{attrs}>"
+
+    return re.sub(r"<h1\b([^>]*)>", repl, body, count=1)
+
+
+def _rewrite_links(
+    body: str, page: Path, prefixes: dict[Path, str], first_ids: dict[Path, str]
+) -> str:
+    def repl(m: re.Match[str]) -> str:
+        before, href, after, inner = m.groups()
+        if not href or href.startswith("#") or _URL_SCHEME.match(href) or href.startswith("//"):
+            return m.group(0)
+        target, _, frag = html.unescape(href).partition("#")
+        target_path = (page.parent / unquote(target)).resolve() if target else page
+        if target_path.is_dir():
+            target_path = target_path / "index.md"
+        if target_path.suffix.lower() not in (".md", ".markdown"):
+            return m.group(0)  # a relative link to some other file; leave it
+        if target_path not in prefixes:
+            log.info(
+                "mkdocs: %s links to %s, which is not in the nav; keeping text only",
+                page.name,
+                target,
+            )
+            return inner
+        anchor = f"{prefixes[target_path]}{frag}" if frag else first_ids.get(target_path)
+        if not anchor:
+            return inner
+        return f'<a{before}href="#{html.escape(anchor)}"{after}>{inner}</a>'
+
+    return _ANCHOR.sub(repl, body)