mkdocstrings-nim 0.2.1

A Nim handler for mkdocstrings

mkdocstrings-nim

Generate API documentation for your Nim projects.

mkdocstrings-nim extracts documentation from Nim source files using the Nim compiler's AST, including module docstrings, procedure signatures, parameter types, return types, and pragma annotations. It renders the documentation as HTML using MkDocs and mkdocstrings.

Full Documentation | Changelog

Quick Start

This guide gets you from zero to a running documentation server for your Nim project.

Prerequisites

• Nim compiler installed and in PATH (install Nim)
• Python 3.9+ (install Python)

1. Install the tools

pip install mkdocs mkdocs-material mkdocstrings-nim

2. Create mkdocs.yml

In your Nim project root, create mkdocs.yml:

site_name: My Nim Project
theme:
  name: material

plugins:
  - search
  - mkdocstrings:
      handlers:
        nim:
          paths: [src]  # Where your .nim files are
          options:
            show_source: true
            docstring_style: rst

3. Create your docs

Create a docs/ directory with an index.md:

mkdir docs

docs/index.md:

# My Nim Project

Welcome to my project documentation.

## API Reference

::: mymodule

The ::: mymodule directive tells mkdocstrings to extract and render documentation from src/mymodule.nim.

4. Run the docs server

mkdocs serve

Open http://127.0.0.1:8000 to see your documentation.

5. Build for deployment

mkdocs build

This creates a site/ directory with static HTML ready to deploy to GitHub Pages, Netlify, or any static host.

Writing Nim Docstrings

Use ## comments to document your Nim code:

## This module provides greeting utilities.

proc greet*(name: string): string =
  ## Greet someone by name.
  ##
  ## :param name: The name to greet
  ## :returns: A greeting message
  result = "Hello, " & name & "!"

type
  Config* = object
    ## Configuration for the greeter.
    prefix*: string  ## The greeting prefix
    suffix*: string  ## The greeting suffix

Supported docstring styles: rst (default), google, numpy, epydoc.

Configuration Options

Configure in mkdocs.yml under plugins > mkdocstrings > handlers > nim > options:

Option	Default	Description
paths	["src"]	Search paths for Nim source files
docstring_style	"rst"	Docstring format: rst, google, numpy, epydoc, auto
show_source	true	Show source file and line numbers
show_signature	true	Show full procedure signatures
show_pragmas	true	Show pragma annotations like {.raises.}
show_private	false	Include non-exported (private) symbols
heading_level	2	Starting heading level for entries
source_url	null	Repository URL for source links (e.g., https://github.com/user/repo)

See the full documentation for more details.

Projects Using mkdocstrings-nim

• nim-typestates - Compile-time state machine verification
• lockfreequeues - Lock-free data structures for Nim

License

MIT