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
