sphinx-mintlify-output 0.1.0__py3-none-any.whl

sphinx_mintlify_output/__init__.py

@@ -0,0 +1,31 @@
+"""Sphinx builder that emits Mintlify-compatible MDX output."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sphinx_mintlify_output.builder import MintlifyBuilder
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.1.0"
+
+__all__ = ["MintlifyBuilder", "__version__", "setup"]
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_builder(MintlifyBuilder)
+    app.add_config_value("mintlify_docs_json", {}, "env")
+    app.add_config_value("mintlify_static_path", [], "env")
+    app.add_config_value("mintlify_image_dir", "images", "env")
+    app.add_config_value("mintlify_frontmatter", {}, "env")
+    app.add_config_value("mintlify_component_map", {}, "env")
+    app.add_config_value("mintlify_emit_anchors", True, "env")
+    app.add_config_value("mintlify_externalize_assets", True, "env")
+    app.add_config_value("mintlify_base_path", "", "env")
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_mintlify_output/assets.py

@@ -0,0 +1,109 @@
+"""Externalize and write image assets referenced from raw HTML blocks.
+
+Sphinx output can embed images two ways the translator has to handle:
+
+* Inline ``<svg>...</svg>`` markup (e.g. from sphinxcontrib-svgbob).
+* Base64 ``data:image/<mime>;base64,...`` URIs.
+
+Both forms inflate the page and can break MDX parsing. The functions
+here write the payload to ``<outdir>/<image_dir>/raw-<sha>.<ext>`` and
+rewrite the HTML to reference the file instead. Asset writes are
+idempotent: identical payloads share a single file.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import os
+import posixpath
+import re
+
+from sphinx_mintlify_output.urls import url_for
+
+SVG_BLOCK_RE = re.compile(r"<svg\b[^>]*>.*?</svg>", re.DOTALL | re.IGNORECASE)
+DATA_URI_RE = re.compile(
+    r"data:image/(?P<mime>png|jpeg|jpg|gif|svg\+xml|webp);base64,"
+    r"(?P<data>[A-Za-z0-9+/=\s]+?)(?=[\"')\s])",
+    re.IGNORECASE,
+)
+MIME_EXT: dict[str, str] = {
+    "png": "png",
+    "jpeg": "jpg",
+    "jpg": "jpg",
+    "gif": "gif",
+    "svg+xml": "svg",
+    "webp": "webp",
+}
+
+
+def externalize_inline_assets(
+    html: str,
+    *,
+    outdir: str,
+    image_dir: str,
+    from_doc: str,
+) -> str:
+    """Replace inline SVG and base64 data: URIs with file references.
+
+    Standalone ``<svg>…</svg>`` blocks are written as ``.svg`` files and
+    replaced with ``<img>`` tags. ``data:image/<mime>;base64,…`` payloads
+    inside larger HTML (typically inside ``<img src="…">``) are written
+    using the inferred extension and only the URI is replaced. Other HTML
+    passes through untouched. URLs are produced via
+    :func:`~sphinx_mintlify_output.urls.url_for` so they respect the
+    relative/absolute mode for the current build.
+    """
+
+    def replace_svg_block(match: re.Match[str]) -> str:
+        svg = match.group(0)
+        rel = write_asset_file(
+            svg.encode("utf-8"),
+            ext="svg",
+            outdir=outdir,
+            image_dir=image_dir,
+            from_doc=from_doc,
+        )
+        return f'<img src="{rel}" />'
+
+    def replace_data_uri(match: re.Match[str]) -> str:
+        mime = match.group("mime").lower()
+        raw = re.sub(r"\s+", "", match.group("data"))
+        ext = MIME_EXT.get(mime, "bin")
+        try:
+            payload = base64.b64decode(raw, validate=True)
+        except (binascii.Error, ValueError):
+            return match.group(0)
+        rel = write_asset_file(
+            payload,
+            ext=ext,
+            outdir=outdir,
+            image_dir=image_dir,
+            from_doc=from_doc,
+        )
+        return rel
+
+    html = SVG_BLOCK_RE.sub(replace_svg_block, html)
+    html = DATA_URI_RE.sub(replace_data_uri, html)
+    return html
+
+
+def write_asset_file(
+    content: bytes,
+    *,
+    ext: str,
+    outdir: str,
+    image_dir: str,
+    from_doc: str,
+) -> str:
+    """Write ``content`` to ``<outdir>/<image_dir>/raw-<hash>.<ext>``."""
+    digest = hashlib.sha256(content).hexdigest()[:16]
+    filename = f"raw-{digest}.{ext}"
+    target_dir = os.path.join(outdir, image_dir)
+    os.makedirs(target_dir, exist_ok=True)
+    target = os.path.join(target_dir, filename)
+    if not os.path.exists(target):
+        with open(target, "wb") as fp:
+            fp.write(content)
+    return url_for(from_doc, posixpath.join(image_dir, filename))

sphinx_mintlify_output/autodoc.py

@@ -0,0 +1,350 @@
+"""Helpers for rendering Sphinx ``desc`` (autodoc) nodes as MDX.
+
+Covers:
+
+* Signature reconstruction (:func:`build_clean_signature`,
+  :func:`decorate_signature`).
+* Heading and label formatting (:func:`format_desc_label`).
+* Parameter parsing for ``Parameters`` field lists
+  (:func:`parse_param_item`, :func:`parse_param_head`,
+  :func:`extract_param_info`).
+* Type-aware cross-referencing of strings like ``list[int] | None``
+  (:func:`link_types_in_string`, :func:`lookup_python_object`).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from docutils import nodes
+
+from sphinx_mintlify_output.state import ParamInfo
+from sphinx_mintlify_output.urls import url_for
+
+
+def desc_short_name(signature: nodes.Element) -> str:
+    """Return the leaf name of a desc_signature (last ``desc_name`` found)."""
+    from sphinx import addnodes
+
+    short = ""
+    for descendant in signature.findall(condition=addnodes.desc_name):
+        short = descendant.astext().strip()
+    return short
+
+
+def decorate_signature(sig: str, desctype: str, return_type: str = "") -> str:
+    """Massage a captured desc signature into a Python-like declaration."""
+    sig = sig.strip()
+    if desctype in {"function", "method", "staticmethod", "classmethod"}:
+        if sig.startswith("async "):
+            sig = "async def " + sig[len("async ") :]
+        elif sig.startswith("classmethod "):
+            sig = "@classmethod def " + sig[len("classmethod ") :]
+        elif sig.startswith("staticmethod "):
+            sig = "@staticmethod def " + sig[len("staticmethod ") :]
+        elif sig.startswith("abstractmethod "):
+            sig = "@abstractmethod def " + sig[len("abstractmethod ") :]
+        else:
+            sig = "def " + sig
+        if return_type and " -> " not in sig:
+            sig = f"{sig} -> {return_type}"
+    return sig
+
+
+def _collect_signature_metadata(
+    signature: nodes.Element,
+    short_name: str,
+) -> tuple[str, str, bool, str]:
+    """Pull (full_name, annotation, has_paramlist, inline_return) from a sig."""
+    from sphinx import addnodes
+
+    full_name = short_name
+    annotation = ""
+    has_paramlist = False
+    inline_return = ""
+    for child in signature.children:
+        if isinstance(child, addnodes.desc_addname):
+            full_name = child.astext().strip() + short_name
+        elif isinstance(child, addnodes.desc_annotation):
+            text = child.astext()
+            if text.startswith(": "):
+                continue
+            annotation = text.strip()
+        elif isinstance(child, addnodes.desc_parameterlist):
+            has_paramlist = True
+        elif isinstance(child, addnodes.desc_returns):
+            text = child.astext().strip()
+            if text.startswith("->"):
+                text = text[2:].strip()
+            elif text.startswith("→"):
+                text = text[1:].strip()
+            inline_return = text
+    return full_name, annotation, has_paramlist, inline_return
+
+
+def _collect_param_names(signature: nodes.Element) -> list[str]:
+    """Extract parameter names from the first parameterlist of ``signature``."""
+    from sphinx import addnodes
+
+    param_names: list[str] = []
+    for plist in signature.findall(condition=addnodes.desc_parameterlist):
+        for param in plist.findall(condition=addnodes.desc_parameter):
+            text = param.astext().strip()
+            if text in {"/", "*"}:
+                param_names.append(text)
+                continue
+            match = SIGNATURE_PARAM_RE.match(text)
+            if match:
+                param_names.append(match.group("name"))
+            else:
+                param_names.append(text.split(":", 1)[0].split("=", 1)[0])
+        break
+    return param_names
+
+
+def _build_class_signature(
+    desctype: str, full_name: str, param_names: list[str]
+) -> str:
+    return f"{desctype} {full_name}({', '.join(param_names)})"
+
+
+def _build_callable_signature(
+    desctype: str,
+    full_name: str,
+    annotation: str,
+    param_names: list[str],
+    return_type: str,
+) -> str:
+    prefix = ""
+    async_kw = ""
+    if annotation == "async":
+        async_kw = "async "
+    elif annotation == "classmethod":
+        prefix = "@classmethod\n"
+    elif annotation == "staticmethod":
+        prefix = "@staticmethod\n"
+    elif annotation == "abstractmethod":
+        prefix = "@abstractmethod\n"
+    if desctype == "classmethod" and "@classmethod" not in prefix:
+        prefix = "@classmethod\n"
+    elif desctype == "staticmethod" and "@staticmethod" not in prefix:
+        prefix = "@staticmethod\n"
+    body = f"{async_kw}def {full_name}({', '.join(param_names)})"
+    if return_type:
+        body = f"{body} -> {return_type}"
+    return prefix + body
+
+
+def _build_property_signature(full_name: str, return_type: str) -> str:
+    body = f"@property\ndef {full_name}()"
+    if return_type:
+        body = f"{body} -> {return_type}"
+    return body
+
+
+def build_clean_signature(
+    signature: nodes.Element,
+    desctype: str,
+    short_name: str,
+    return_type: str = "",
+) -> str:
+    """Reconstruct a parameter-name-only signature with decorators."""
+    full_name, annotation, has_paramlist, inline_return = _collect_signature_metadata(
+        signature, short_name
+    )
+    if inline_return and not return_type:
+        return_type = inline_return
+    param_names = _collect_param_names(signature) if has_paramlist else []
+
+    if desctype in {"class", "exception"}:
+        return _build_class_signature(desctype, full_name, param_names)
+    if desctype in {"function", "method", "staticmethod", "classmethod"}:
+        return _build_callable_signature(
+            desctype, full_name, annotation, param_names, return_type
+        )
+    if desctype == "property":
+        return _build_property_signature(full_name, return_type)
+    return full_name
+
+
+def format_desc_label(desctype: str, short_name: str) -> str:
+    """Return the heading label for a desc node, with type prefix when useful."""
+    if not short_name:
+        return desctype or "object"
+    if desctype == "class":
+        return f"`class {short_name}`"
+    if desctype == "exception":
+        return f"`exception {short_name}`"
+    if desctype in {"function", "method", "staticmethod", "classmethod"}:
+        return f"`{short_name}()`"
+    return f"`{short_name}`"
+
+
+# Matches a single token from a Sphinx ``desc_parameterlist`` —
+# ``name``, ``name: type``, ``name = default``, ``name: type = default``,
+# ``*args`` / ``**kwargs``.
+SIGNATURE_PARAM_RE = re.compile(
+    r"^(?P<name>\*{0,2}\w+)"
+    r"\s*(?::\s*(?P<type>[^=]+?))?"
+    r"\s*(?:=\s*(?P<default>.+))?$",
+    re.DOTALL,
+)
+
+
+def extract_param_info(desc_node: nodes.Element) -> dict[str, ParamInfo]:
+    """Pull per-parameter type/default/required info from a desc node."""
+    from sphinx import addnodes
+
+    info: dict[str, ParamInfo] = {}
+    for plist in desc_node.findall(condition=addnodes.desc_parameterlist):
+        for param in plist.findall(condition=addnodes.desc_parameter):
+            text = param.astext().strip()
+            if text in {"/", "*"}:
+                continue
+            match = SIGNATURE_PARAM_RE.match(text)
+            if match is None:
+                continue
+            name = (match.group("name") or "").strip()
+            if not name:
+                continue
+            type_str = (match.group("type") or "").strip()
+            default = (match.group("default") or "").strip()
+            is_varargs = name.startswith("*")
+            info[name] = {
+                "type": type_str,
+                "default": default,
+                "required": not default and not is_varargs,
+            }
+        break
+    return info
+
+
+EN_DASH = chr(0x2013)
+EM_DASH = chr(0x2014)
+PARAM_DASH_SEPARATORS = (f" {EN_DASH} ", f" {EM_DASH} ", " -- ")
+PARAM_DASH_CLASS = "[-" + EN_DASH + EM_DASH + "]+"
+# Matches one rendered docstring param line — ``name(type) -- description``
+# or any of the dash variants. Used by :func:`parse_param_item` to peel
+# ``:param X: text`` items rendered by Sphinx into the body field list.
+DOCSTRING_PARAM_RE = re.compile(
+    "^\\s*(?P<name>\\S+?)\\s*(?:\\((?P<type>[^)]*)\\))?\\s*"
+    + PARAM_DASH_CLASS
+    + "\\s*(?P<desc>.*)$",
+    re.DOTALL,
+)
+
+
+TYPE_TOKEN_RE = re.compile(r"([A-Za-z_][\w.]*)")
+
+
+def lookup_python_object(env: Any, name: str) -> tuple[str, str] | None:
+    """Find a Python-domain class/exception/function by short or full name.
+
+    Returns ``(docname, anchor)`` or ``None`` when nothing matches.
+    """
+    try:
+        domain = env.get_domain("py")
+    except Exception:
+        return None
+    objects = getattr(domain, "objects", None)
+    if not objects:
+        return None
+    entry = objects.get(name)
+    if entry is not None:
+        objtype = getattr(entry, "objtype", "")
+        if objtype in {"class", "exception", "function", "method"}:
+            return getattr(entry, "docname", ""), getattr(entry, "node_id", "")
+    suffix = "." + name
+    for fullname, found in objects.items():
+        if fullname == name or fullname.endswith(suffix):
+            objtype = getattr(found, "objtype", "")
+            if objtype in {"class", "exception", "function", "method"}:
+                return getattr(found, "docname", ""), getattr(found, "node_id", "")
+    return None
+
+
+def link_types_in_string(type_str: str, from_doc: str, env: Any) -> str:
+    """Wrap recognised class names inside a type expression with markdown links."""
+    if not type_str:
+        return ""
+
+    def replace(match: re.Match[str]) -> str:
+        token = match.group(1)
+        if token in BUILTIN_TYPE_NAMES:
+            return token
+        ref = lookup_python_object(env, token)
+        if ref is None:
+            return token
+        docname, anchor = ref
+        href = url_for(from_doc, docname)
+        if anchor:
+            href = href + "#" + anchor
+        return f"[`{token}`]({href})"
+
+    return TYPE_TOKEN_RE.sub(replace, type_str)
+
+
+BUILTIN_TYPE_NAMES: frozenset[str] = frozenset(
+    {
+        "Any",
+        "Awaitable",
+        "Callable",
+        "ClassVar",
+        "Dict",
+        "Final",
+        "Generator",
+        "Iterable",
+        "Iterator",
+        "List",
+        "Literal",
+        "Mapping",
+        "None",
+        "Optional",
+        "Path",
+        "PurePosixPath",
+        "Sequence",
+        "Set",
+        "Tuple",
+        "Type",
+        "TypeVar",
+        "Union",
+        "UUID",
+        "bool",
+        "bytes",
+        "datetime",
+        "dict",
+        "float",
+        "frozenset",
+        "int",
+        "list",
+        "object",
+        "set",
+        "str",
+        "timedelta",
+        "tuple",
+        "type",
+    }
+)
+
+
+def parse_param_item(item: nodes.Element) -> tuple[str, str, str]:
+    """Extract (name, type, description) from a Sphinx autodoc param item."""
+    text = item.astext().strip()
+    match = DOCSTRING_PARAM_RE.match(text)
+    if match:
+        return (
+            match.group("name"),
+            (match.group("type") or "").strip(),
+            (match.group("desc") or "").strip(),
+        )
+    parts = text.split(None, 1)
+    if len(parts) == 2:
+        return parts[0], "", parts[1]
+    return text, "", ""
+
+
+def parse_param_head(item: nodes.Element) -> tuple[str, str]:
+    """Extract only (name, type) from a Sphinx autodoc param item."""
+    name, type_str, _ = parse_param_item(item)
+    return name, type_str