mkdocstrings-nim 0.1.0__py3-none-any.whl

mkdocstrings_handlers/__init__.py

@@ -0,0 +1,2 @@
+"""mkdocstrings handlers namespace package."""
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

mkdocstrings_handlers/nim/__init__.py

@@ -0,0 +1,27 @@
+"""Nim handler for mkdocstrings."""
+
+from mkdocstrings_handlers.nim.handler import NimHandler, get_handler
+from mkdocstrings_handlers.nim.collector import NimCollector, NimModule, NimEntry, NimParam
+from mkdocstrings_handlers.nim.docstring import (
+    parse_docstring,
+    DocstringStyle,
+    ParsedDocstring,
+    ParamDoc,
+    ReturnsDoc,
+    RaisesDoc,
+)
+
+__all__ = [
+    "NimHandler",
+    "get_handler",
+    "NimCollector",
+    "NimModule",
+    "NimEntry",
+    "NimParam",
+    "parse_docstring",
+    "DocstringStyle",
+    "ParsedDocstring",
+    "ParamDoc",
+    "ReturnsDoc",
+    "RaisesDoc",
+]

mkdocstrings_handlers/nim/collector.py

@@ -0,0 +1,267 @@
+"""Collector for Nim documentation."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from importlib.resources import files, as_file
+from pathlib import Path
+from typing import Any
+
+from mkdocstrings import CollectionError
+
+# Cache directory for compiled nimdocinfo binary
+_CACHE_DIR = Path(tempfile.gettempdir()) / "mkdocstrings-nim-cache"
+
+
+@dataclass
+class NimParam:
+    """A Nim parameter."""
+    name: str
+    type: str
+    description: str = ""
+
+
+@dataclass
+class NimEntry:
+    """A documented Nim entry (proc, type, const, etc.)."""
+    name: str
+    kind: str
+    line: int
+    signature: str
+    doc: str = ""
+    params: list[NimParam] = field(default_factory=list)
+    returns: str = ""
+    returns_doc: str = ""
+    pragmas: list[str] = field(default_factory=list)
+    raises: list[str] = field(default_factory=list)
+
+
+@dataclass
+class NimModule:
+    """A documented Nim module."""
+    module: str
+    file: str
+    doc: str = ""
+    entries: list[NimEntry] = field(default_factory=list)
+
+
+class NimCollector:
+    """Collects documentation from Nim source files."""
+
+    def __init__(self, paths: list[str], base_dir: Path):
+        """Initialize the collector.
+
+        Args:
+            paths: Search paths for Nim source files.
+            base_dir: Base directory of the project.
+        """
+        self.paths = paths
+        self.base_dir = base_dir
+        self._cache: dict[str, NimModule] = {}
+        # Use importlib.resources for reliable path resolution
+        extractor_files = files("mkdocstrings_handlers.nim").joinpath("extractor")
+        self._nimdocinfo_source = extractor_files.joinpath("nimdocinfo.nim")
+
+    def _resolve_identifier(self, identifier: str) -> Path:
+        """Resolve a module identifier to a file path.
+
+        Args:
+            identifier: Module identifier like 'lockfreequeues.ops'
+
+        Returns:
+            Path to the Nim source file.
+
+        Raises:
+            CollectionError: If the file cannot be found.
+        """
+        # Convert dots to path separators
+        rel_path = identifier.replace(".", "/") + ".nim"
+
+        for search_path in self.paths:
+            full_path = self.base_dir / search_path / rel_path
+            if full_path.exists():
+                return full_path
+
+        # Try without nested path (just filename)
+        filename = identifier.split(".")[-1] + ".nim"
+        for search_path in self.paths:
+            full_path = self.base_dir / search_path / filename
+            if full_path.exists():
+                return full_path
+
+        raise CollectionError(f"Could not find Nim file for identifier: {identifier}")
+
+    def _ensure_nimdocinfo_compiled(self) -> Path:
+        """Ensure nimdocinfo is compiled and return path to binary.
+
+        Copies Nim source files to a cache directory and compiles them there.
+        This avoids writing to the installed package directory.
+
+        Returns:
+            Path to the compiled nimdocinfo binary.
+
+        Raises:
+            CollectionError: If compilation fails.
+        """
+        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Get the extractor package files
+        extractor_pkg = files("mkdocstrings_handlers.nim").joinpath("extractor")
+
+        # Copy source files to cache if needed
+        with as_file(extractor_pkg.joinpath("nimdocinfo.nim")) as src_main:
+            with as_file(extractor_pkg.joinpath("extractor.nim")) as src_extractor:
+                cache_main = _CACHE_DIR / "nimdocinfo.nim"
+                cache_extractor = _CACHE_DIR / "extractor.nim"
+                cache_binary = _CACHE_DIR / "nimdocinfo"
+
+                # Check if we need to recompile (source newer than binary)
+                needs_compile = not cache_binary.exists()
+                if not needs_compile:
+                    binary_mtime = cache_binary.stat().st_mtime
+                    if src_main.stat().st_mtime > binary_mtime:
+                        needs_compile = True
+                    elif src_extractor.stat().st_mtime > binary_mtime:
+                        needs_compile = True
+
+                if needs_compile:
+                    # Copy source files
+                    shutil.copy2(src_main, cache_main)
+                    shutil.copy2(src_extractor, cache_extractor)
+
+                    # Compile (first run is slow, ~15s; subsequent runs use cache)
+                    result = subprocess.run(
+                        ["nim", "c", "--outdir:" + str(_CACHE_DIR), str(cache_main)],
+                        capture_output=True,
+                        text=True,
+                        timeout=120,  # First compile can be slow
+                    )
+
+                    if result.returncode != 0:
+                        raise CollectionError(
+                            f"Failed to compile nimdocinfo:\n{result.stderr}"
+                        )
+
+                return cache_binary
+
+    def _run_nimdocinfo(self, filepath: Path) -> dict[str, Any]:
+        """Run nimdocinfo on a Nim file.
+
+        Args:
+            filepath: Path to the Nim source file.
+
+        Returns:
+            Parsed JSON output from nimdocinfo.
+
+        Raises:
+            CollectionError: If nimdocinfo fails.
+        """
+        try:
+            binary_path = self._ensure_nimdocinfo_compiled()
+
+            result = subprocess.run(
+                [str(binary_path), str(filepath)],
+                capture_output=True,
+                text=True,
+                cwd=str(self.base_dir),
+                timeout=60,
+            )
+
+            if result.returncode != 0:
+                raise CollectionError(
+                    f"nimdocinfo failed:\n{result.stderr}\n\n"
+                    f"To debug, run manually:\n"
+                    f"  {binary_path} {filepath}"
+                )
+
+            # Parse JSON from stdout
+            lines = result.stdout.strip().split("\n")
+            json_lines = []
+            in_json = False
+            for line in lines:
+                if line.strip().startswith("{"):
+                    in_json = True
+                if in_json:
+                    json_lines.append(line)
+                if in_json and line.strip().startswith("}") and len(json_lines) > 1:
+                    try:
+                        return json.loads("\n".join(json_lines))
+                    except json.JSONDecodeError:
+                        continue
+
+            if not json_lines:
+                raise CollectionError(f"No JSON output from nimdocinfo: {result.stdout}")
+
+            return json.loads("\n".join(json_lines))
+
+        except FileNotFoundError:
+            raise CollectionError(
+                "Nim compiler not found. Install from https://nim-lang.org/install.html\n"
+                "Then verify installation: nim --version"
+            )
+        except subprocess.TimeoutExpired:
+            raise CollectionError(
+                f"nimdocinfo timed out processing {filepath}. "
+                "The file may be too complex or have circular imports."
+            )
+        except json.JSONDecodeError as e:
+            raise CollectionError(f"Invalid JSON from nimdocinfo: {e}")
+
+    def _parse_module(self, data: dict[str, Any]) -> NimModule:
+        """Parse JSON data into NimModule.
+
+        Args:
+            data: JSON data from nimdocinfo.
+
+        Returns:
+            Parsed NimModule.
+        """
+        entries = []
+        for entry_data in data.get("entries", []):
+            params = [
+                NimParam(name=p["name"], type=p["type"])
+                for p in entry_data.get("params", [])
+            ]
+
+            entries.append(NimEntry(
+                name=entry_data["name"],
+                kind=entry_data["kind"],
+                line=entry_data["line"],
+                signature=entry_data["signature"],
+                doc=entry_data.get("doc", ""),
+                params=params,
+                returns=entry_data.get("returns", ""),
+                pragmas=entry_data.get("pragmas", []),
+                raises=entry_data.get("raises", []),
+            ))
+
+        return NimModule(
+            module=data["module"],
+            file=data["file"],
+            doc=data.get("doc", ""),
+            entries=entries,
+        )
+
+    def collect(self, identifier: str) -> NimModule:
+        """Collect documentation for a module identifier.
+
+        Args:
+            identifier: Module identifier like 'lockfreequeues.ops'
+
+        Returns:
+            NimModule with documentation.
+        """
+        if identifier in self._cache:
+            return self._cache[identifier]
+
+        filepath = self._resolve_identifier(identifier)
+        data = self._run_nimdocinfo(filepath)
+        module = self._parse_module(data)
+
+        self._cache[identifier] = module
+        return module

mkdocstrings_handlers/nim/docstring.py

@@ -0,0 +1,129 @@
+"""Docstring parsing for Nim documentation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+import docstring_parser
+from docstring_parser import DocstringStyle as DPStyle
+
+
+class DocstringStyle(Enum):
+    """Supported docstring styles."""
+    RST = "rst"
+    GOOGLE = "google"
+    NUMPY = "numpy"
+    EPYDOC = "epydoc"
+    AUTO = "auto"
+
+
+@dataclass
+class ParamDoc:
+    """Parsed parameter documentation."""
+    name: str
+    description: str = ""
+    type: str = ""
+
+
+@dataclass
+class ReturnsDoc:
+    """Parsed return value documentation."""
+    description: str = ""
+    type: str = ""
+
+
+@dataclass
+class RaisesDoc:
+    """Parsed raises documentation."""
+    type: str
+    description: str = ""
+
+
+@dataclass
+class ParsedDocstring:
+    """Parsed docstring with structured sections."""
+    description: str = ""
+    params: list[ParamDoc] = field(default_factory=list)
+    returns: Optional[ReturnsDoc] = None
+    raises: list[RaisesDoc] = field(default_factory=list)
+    examples: list[str] = field(default_factory=list)
+
+
+# Map our style enum to docstring_parser's style enum
+_STYLE_MAP = {
+    DocstringStyle.RST: DPStyle.REST,
+    DocstringStyle.GOOGLE: DPStyle.GOOGLE,
+    DocstringStyle.NUMPY: DPStyle.NUMPYDOC,
+    DocstringStyle.EPYDOC: DPStyle.EPYDOC,
+    DocstringStyle.AUTO: DPStyle.AUTO,
+}
+
+
+def parse_docstring(doc: str, style: DocstringStyle = DocstringStyle.RST) -> ParsedDocstring:
+    """Parse a docstring according to the specified style.
+
+    Uses the docstring_parser library for robust parsing of RST, Google,
+    and NumPy docstring formats.
+
+    Args:
+        doc: Raw docstring text.
+        style: Docstring style to use for parsing.
+
+    Returns:
+        Parsed docstring structure.
+    """
+    if not doc:
+        return ParsedDocstring()
+
+    dp_style = _STYLE_MAP.get(style, DPStyle.REST)
+
+    try:
+        parsed = docstring_parser.parse(doc, style=dp_style)
+    except Exception:
+        # Fall back to auto-detection if specified style fails
+        try:
+            parsed = docstring_parser.parse(doc)
+        except Exception:
+            # If all parsing fails, just return description
+            return ParsedDocstring(description=doc.strip())
+
+    result = ParsedDocstring()
+
+    # Extract description (short + long)
+    desc_parts = []
+    if parsed.short_description:
+        desc_parts.append(parsed.short_description)
+    if parsed.long_description:
+        desc_parts.append(parsed.long_description)
+    result.description = "\n\n".join(desc_parts)
+
+    # Extract parameters
+    for param in parsed.params:
+        result.params.append(ParamDoc(
+            name=param.arg_name,
+            description=param.description or "",
+            type=param.type_name or "",
+        ))
+
+    # Extract returns
+    if parsed.returns:
+        result.returns = ReturnsDoc(
+            description=parsed.returns.description or "",
+            type=parsed.returns.type_name or "",
+        )
+
+    # Extract raises
+    for raises in parsed.raises:
+        result.raises.append(RaisesDoc(
+            type=raises.type_name or "",
+            description=raises.description or "",
+        ))
+
+    # Extract examples
+    for example in parsed.examples:
+        if example.description:
+            result.examples.append(example.description)
+
+    return result

mkdocstrings_handlers/nim/extractor/extractor.nim

@@ -0,0 +1,244 @@
+## AST extraction logic for nimdocinfo
+import std/[json, strutils, sequtils, os]
+import compiler/[ast, parser, idents, options, pathutils, lineinfos, msgs, renderer, llstream]
+
+type
+  DocEntry* = object
+    name*: string
+    kind*: string
+    line*: int
+    signature*: string
+    params*: seq[tuple[name, typ: string]]
+    returns*: string
+    pragmas*: seq[string]
+    raises*: seq[string]
+    doc*: string
+
+  ModuleDoc* = object
+    module*: string
+    file*: string
+    doc*: string
+    entries*: seq[DocEntry]
+
+proc extractDocComment(n: PNode): string =
+  ## Extract doc comment from a node
+  if n == nil:
+    return ""
+  if n.comment.len > 0:
+    return n.comment.strip
+  return ""
+
+proc extractPragmas(n: PNode): seq[string] =
+  ## Extract pragma names from a pragma node
+  result = @[]
+  if n == nil or n.kind != nkPragma:
+    return
+  for child in n:
+    if child.kind == nkIdent:
+      result.add($child.ident.s)
+    elif child.kind == nkExprColonExpr and child[0].kind == nkIdent:
+      result.add($child[0].ident.s)
+
+proc extractRaises(n: PNode): seq[string] =
+  ## Extract exception types from raises pragma
+  ## e.g., {.raises: [ValueError, IOError].}
+  result = @[]
+  if n == nil or n.kind != nkPragma:
+    return
+  for child in n:
+    if child.kind == nkExprColonExpr and child.len >= 2:
+      if child[0].kind == nkIdent and $child[0].ident.s == "raises":
+        let bracket = child[1]
+        if bracket.kind == nkBracket:
+          for exc in bracket:
+            if exc.kind == nkIdent:
+              result.add($exc.ident.s)
+            elif exc.kind == nkDotExpr:
+              # Handle qualified names like system.Exception
+              result.add($exc)
+
+proc extractParams(n: PNode): seq[tuple[name, typ: string]] =
+  ## Extract parameter list from formal params
+  result = @[]
+  if n == nil or n.kind != nkFormalParams:
+    return
+  # Skip first child (return type)
+  for i in 1..<n.len:
+    let param = n[i]
+    if param.kind == nkIdentDefs:
+      let typNode = param[^2]
+      let typStr = if typNode.kind == nkEmpty: "auto" else: $typNode
+      # All names except last two (type and default)
+      for j in 0..<param.len - 2:
+        if param[j].kind == nkIdent:
+          result.add(($param[j].ident.s, typStr))
+
+proc extractReturnType(n: PNode): string =
+  ## Extract return type from formal params
+  if n == nil or n.kind != nkFormalParams or n.len == 0:
+    return ""
+  let retNode = n[0]
+  if retNode.kind == nkEmpty:
+    return ""
+  return $retNode
+
+const
+  # Nim AST indices for routine (proc/func/etc) nodes
+  routineNameIdx = 0
+  routinePatternIdx = 1
+  routineGenericParamsIdx = 2
+  routineParamsIdx = 3
+  routinePragmasIdx = 4
+  routineBodyIdx = 6
+
+proc renderSignature(n: PNode, kind: string, name: string): string =
+  ## Render full signature as string
+  result = kind & " " & name
+  if n.len > routineParamsIdx and n[routineParamsIdx].kind == nkFormalParams:
+    let params = n[routineParamsIdx]
+    var paramStrs: seq[string] = @[]
+    for i in 1..<params.len:
+      paramStrs.add($params[i])
+    result &= "(" & paramStrs.join("; ") & ")"
+    let ret = extractReturnType(n[routineParamsIdx])
+    if ret.len > 0:
+      result &= ": " & ret
+
+proc extractName(n: PNode): string =
+  ## Extract name from a name node (handles postfix for exported symbols)
+  if n.kind == nkIdent:
+    return $n.ident.s
+  elif n.kind == nkPostfix and n.len >= 2 and n[1].kind == nkIdent:
+    return $n[1].ident.s
+  elif n.kind == nkPostfix and n.len >= 2 and n[1].kind == nkAccQuoted:
+    # Handle quoted operators like `+`*
+    if n[1].len > 0 and n[1][0].kind == nkIdent:
+      return $n[1][0].ident.s
+  return ""
+
+proc extractProcDoc(n: PNode): string =
+  ## Extract doc comment from a proc definition
+  ## The doc comment can be on the proc node itself or on the first statement in the body
+  result = extractDocComment(n)
+  if result.len == 0 and n.len > routineBodyIdx:
+    let body = n[routineBodyIdx]
+    if body != nil and body.kind == nkStmtList and body.len > 0:
+      # Check if first statement has a comment
+      result = extractDocComment(body[0])
+      if result.len == 0 and body[0].kind == nkCommentStmt:
+        result = body[0].comment.strip
+
+proc extractProc(n: PNode, kind: string): DocEntry =
+  ## Extract documentation from a proc/func/etc definition
+  result.name = extractName(n[routineNameIdx])
+  result.kind = kind
+  result.line = n.info.line.int
+  result.doc = extractProcDoc(n)
+
+  if n.len > routineParamsIdx:
+    result.params = extractParams(n[routineParamsIdx])
+    result.returns = extractReturnType(n[routineParamsIdx])
+
+  # Extract pragmas at the correct index
+  if n.len > routinePragmasIdx and n[routinePragmasIdx].kind == nkPragma:
+    result.pragmas = extractPragmas(n[routinePragmasIdx])
+    result.raises = extractRaises(n[routinePragmasIdx])
+
+  result.signature = renderSignature(n, kind, result.name)
+
+proc extractType(n: PNode): DocEntry =
+  ## Extract documentation from a type definition
+  result.kind = "type"
+  result.doc = extractDocComment(n)
+  result.line = n.info.line.int
+  result.name = extractName(n[0])
+  result.signature = "type " & result.name
+
+proc extractConst(n: PNode): DocEntry =
+  ## Extract documentation from a const definition
+  result.kind = "const"
+  result.doc = extractDocComment(n)
+  result.line = n.info.line.int
+  result.name = extractName(n[0])
+  result.signature = "const " & result.name
+
+proc walkAst(n: PNode, entries: var seq[DocEntry]) =
+  ## Walk AST and collect documentation entries
+  if n == nil:
+    return
+
+  case n.kind
+  of nkProcDef:
+    entries.add extractProc(n, "proc")
+  of nkFuncDef:
+    entries.add extractProc(n, "func")
+  of nkIteratorDef:
+    entries.add extractProc(n, "iterator")
+  of nkTemplateDef:
+    entries.add extractProc(n, "template")
+  of nkMacroDef:
+    entries.add extractProc(n, "macro")
+  of nkTypeDef:
+    entries.add extractType(n)
+  of nkConstDef:
+    entries.add extractConst(n)
+  else:
+    for child in n:
+      walkAst(child, entries)
+
+proc extractModule*(filepath: string): ModuleDoc =
+  ## Extract all documentation from a Nim source file
+  result.file = filepath
+  result.module = filepath.splitFile.name
+  result.entries = @[]
+
+  # Parse the file
+  var conf = newConfigRef()
+  conf.verbosity = 0
+
+  let fileIdx = fileInfoIdx(conf, AbsoluteFile(filepath))
+  var parser: Parser
+
+  let source = readFile(filepath)
+  openParser(parser, fileIdx, llStreamOpen(source), newIdentCache(), conf)
+
+  let ast = parseAll(parser)
+  closeParser(parser)
+
+  # Extract module doc comment
+  if ast.len > 0 and ast[0].comment.len > 0:
+    result.doc = ast[0].comment.strip
+
+  walkAst(ast, result.entries)
+
+proc toJson*(doc: ModuleDoc): JsonNode =
+  ## Convert module documentation to JSON
+  result = %*{
+    "module": doc.module,
+    "file": doc.file,
+    "doc": doc.doc,
+    "entries": []
+  }
+
+  for entry in doc.entries:
+    var entryJson = %*{
+      "name": entry.name,
+      "kind": entry.kind,
+      "line": entry.line,
+      "signature": entry.signature,
+      "doc": entry.doc
+    }
+
+    if entry.params.len > 0:
+      entryJson["params"] = %entry.params.mapIt(%*{"name": it.name, "type": it.typ})
+
+    if entry.returns.len > 0:
+      entryJson["returns"] = %entry.returns
+
+    if entry.pragmas.len > 0:
+      entryJson["pragmas"] = %entry.pragmas
+
+    if entry.raises.len > 0:
+      entryJson["raises"] = %entry.raises
+
+    result["entries"].add entryJson

mkdocstrings_handlers/nim/extractor/nimdocinfo.nim

@@ -0,0 +1,16 @@
+## nimdocinfo - Extract documentation from Nim source files
+import std/[json, os]
+import extractor
+
+when isMainModule:
+  if paramCount() < 1:
+    echo "Usage: nimdocinfo <file.nim>"
+    quit(1)
+
+  let filepath = paramStr(1)
+  if not fileExists(filepath):
+    echo "Error: File not found: ", filepath
+    quit(1)
+
+  let doc = extractModule(filepath)
+  echo doc.toJson.pretty