mkdocstrings-nim 0.1.0__tar.gz

mkdocstrings_nim-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Nim
+nimcache/
+*.exe
+*.out
+src/nimdocinfo/nimdocinfo
+
+# MkDocs
+site/
+docs/plans/
+
+# OS
+.DS_Store
+Thumbs.db

mkdocstrings_nim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Elijah Rutschman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocstrings_nim-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: mkdocstrings-nim
+Version: 0.1.0
+Summary: A Nim handler for mkdocstrings
+Author: Elijah Rutschman
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Requires-Dist: docstring-parser>=0.15
+Requires-Dist: jinja2>=3.0
+Requires-Dist: mkdocstrings>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike>=2.0; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == 'docs'
+Requires-Dist: mkdocs-glightbox>=0.3; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# mkdocstrings-nim
+
+[![PyPI](https://img.shields.io/pypi/v/mkdocstrings-nim)](https://pypi.org/project/mkdocstrings-nim/)
+[![Python](https://img.shields.io/pypi/pyversions/mkdocstrings-nim)](https://pypi.org/project/mkdocstrings-nim/)
+[![License](https://img.shields.io/github/license/elijahr/mkdocstrings-nim)](https://github.com/elijahr/mkdocstrings-nim/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-elijahr.github.io%2Fmkdocstrings--nim-blue)](https://elijahr.github.io/mkdocstrings-nim/)
+
+A [mkdocstrings](https://mkdocstrings.github.io/) handler for [Nim](https://nim-lang.org/).
+
+Parses Nim source files using the Nim compiler's AST to extract module docstrings, procedure signatures, parameter types, return types, and `{.raises.}` pragma annotations. Renders the extracted documentation as HTML within [MkDocs](https://www.mkdocs.org/) using the `::: module` directive syntax.
+
+**[Documentation](https://elijahr.github.io/mkdocstrings-nim/)**
+
+## Installation
+
+```bash
+pip install mkdocstrings-nim
+```
+
+**Requirements:** Nim compiler must be installed and available in PATH.
+
+## Quick Start
+
+1. Add to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - mkdocstrings:
+      handlers:
+        nim:
+          paths: [src]
+```
+
+2. Use in your markdown:
+
+```markdown
+# API Reference
+
+::: mymodule
+```
+
+3. Build your docs:
+
+```bash
+mkdocs build
+```
+
+## Configuration
+
+### Handler Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `paths` | `["src"]` | Search paths for Nim source files |
+| `docstring_style` | `"rst"` | Docstring format: `rst`, `google`, `numpy`, `epydoc`, or `auto` |
+| `show_source` | `true` | Show source line numbers |
+| `show_signature` | `true` | Show full signatures |
+| `show_pragmas` | `true` | Show pragma annotations |
+
+### Docstring Format
+
+Use RST-style docstrings in your Nim code:
+
+```nim
+proc greet*(name: string): string =
+  ## Greet someone by name.
+  ##
+  ## :param name: The name to greet
+  ## :returns: A greeting message
+  result = "Hello, " & name & "!"
+```
+
+## Development
+
+```bash
+git clone https://github.com/elijahr/mkdocstrings-nim
+cd mkdocstrings-nim
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mkdocstrings_nim-0.1.0/README.md

@@ -0,0 +1,84 @@
+# mkdocstrings-nim
+
+[![PyPI](https://img.shields.io/pypi/v/mkdocstrings-nim)](https://pypi.org/project/mkdocstrings-nim/)
+[![Python](https://img.shields.io/pypi/pyversions/mkdocstrings-nim)](https://pypi.org/project/mkdocstrings-nim/)
+[![License](https://img.shields.io/github/license/elijahr/mkdocstrings-nim)](https://github.com/elijahr/mkdocstrings-nim/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-elijahr.github.io%2Fmkdocstrings--nim-blue)](https://elijahr.github.io/mkdocstrings-nim/)
+
+A [mkdocstrings](https://mkdocstrings.github.io/) handler for [Nim](https://nim-lang.org/).
+
+Parses Nim source files using the Nim compiler's AST to extract module docstrings, procedure signatures, parameter types, return types, and `{.raises.}` pragma annotations. Renders the extracted documentation as HTML within [MkDocs](https://www.mkdocs.org/) using the `::: module` directive syntax.
+
+**[Documentation](https://elijahr.github.io/mkdocstrings-nim/)**
+
+## Installation
+
+```bash
+pip install mkdocstrings-nim
+```
+
+**Requirements:** Nim compiler must be installed and available in PATH.
+
+## Quick Start
+
+1. Add to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - mkdocstrings:
+      handlers:
+        nim:
+          paths: [src]
+```
+
+2. Use in your markdown:
+
+```markdown
+# API Reference
+
+::: mymodule
+```
+
+3. Build your docs:
+
+```bash
+mkdocs build
+```
+
+## Configuration
+
+### Handler Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `paths` | `["src"]` | Search paths for Nim source files |
+| `docstring_style` | `"rst"` | Docstring format: `rst`, `google`, `numpy`, `epydoc`, or `auto` |
+| `show_source` | `true` | Show source line numbers |
+| `show_signature` | `true` | Show full signatures |
+| `show_pragmas` | `true` | Show pragma annotations |
+
+### Docstring Format
+
+Use RST-style docstrings in your Nim code:
+
+```nim
+proc greet*(name: string): string =
+  ## Greet someone by name.
+  ##
+  ## :param name: The name to greet
+  ## :returns: A greeting message
+  result = "Hello, " & name & "!"
+```
+
+## Development
+
+```bash
+git clone https://github.com/elijahr/mkdocstrings-nim
+cd mkdocstrings-nim
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mkdocstrings_nim-0.1.0/mkdocstrings_handlers/__init__.py

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

mkdocstrings_nim-0.1.0/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_nim-0.1.0/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_nim-0.1.0/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