Metadata-Version: 2.4
Name: mkdocstrings-dart
Version: 0.1.0
Summary: Dart handler for mkdocstrings
Author: Andrew Murphy
License-Expression: MIT
Project-URL: source, https://github.com/andrewmurphy353/mkdocstrings-dart.git
Project-URL: changelog, https://github.com/andrewmurphy353/mkdocstrings-dart/blob/main/CHANGELOG.md
Project-URL: issues, https://github.com/andrewmurphy353/mkdocstrings-dart/issues
Keywords: dart,mkdocs,mkdocs-plugin,mkdocstrings
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocstrings>=1.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: mkdocs-material>=9.7.1; extra == "dev"
Requires-Dist: pymdown-extensions>=10.20; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Dynamic: license-file

# mkdocstrings-dart

![License](https://img.shields.io/github/license/andrewmurphy353/mkdocstrings-dart?logo=github)

A Dart handler for [mkdocstrings](https://mkdocstrings.github.io/), bringing beautiful, automatic API documentation to Dart packages in MkDocs.

Powered by [`dartdoc_json`](https://pub.dev/packages/dartdoc_json), it extracts doc comments, signatures, parameters, return types, and source code from your Dart libraries — no extra configuration needed.

## Features

- Renders classes, constructors, methods, getters/setters
- Parameter tables with names, types, and defaults  
  (Parameter descriptions appear in the main method docstring)
- Return type display
- Collapsible source code with Dart syntax highlighting
- Auto-detects your package name from `pubspec.yaml`
- Supports both `::: package.Class` and `::: Class` identifiers
- Respects `paths`, `exclude_files`, and `show_source` options
- Modern, wide, responsive styling

## Installation

```bash
pip install mkdocstrings-dart
dart pub global activate dartdoc_json
```

> **Note**: `dartdoc_json` is required to parse Dart source. It's lightweight and uses the official Dart analyzer.

## Usage

> **Note**: When using **mkdocstrings-dart** alongside other handlers (e.g., the default Python handler), you **must** explicitly set the default handler if you want Dart to be used for unmarked `:::` blocks, otherwise define the handler with each block definition.

In your `mkdocs.yml`:

```yaml
plugins:
  - mkdocstrings:
      default_handler: dart   # <- Required if you want ::: Identifier to use Dart by default
      handlers:
        dart:
          options:
            paths: ["lib"]                # Default: ["lib"]
            show_source: true             # Show collapsible source code
            exclude_files: ["curo.dart"]  # Optional: skip barrel files
```

**Options**

Option|Type|Default|Description
------|----|-------|-----------
`paths`|list[str]|`["lib"]`|Directories to scan for `.dart` files
`show_source`|bool|`true`|Show source code in a collapsible panel
`exclude_files`|list[str]|`[]`|Basenames of files to skip (e.g., barrel files)
`heading_level`|int|`2`|Starting heading level for rendered docs


Then in your Markdown files:

```md
# Calculator API

::: <package-name>.Calculator
# or simply
::: Calculator
```
## Rendered Example

Below is exactly how the above `::: Calculator` markdown will appear in your final HTML documentation site:

![Screenshot of rendered Dart docs using the included example](docs/assets/screenshot.png)

## Development

```bash
# Editable install
pip install -e .
dart pub global activate dartdoc_json
mkdocs serve
```

## Roadmap

- Support for library-level overviews
- Cross-references between classes
- Better handling of generics and annotations
- Material for MkDocs theme integration tweaks

## Credits

Built with inspiration from the official mkdocstrings Python handler and powered by the excellent `dartdoc_json` tool.

Made with :heart: for the Dart community.
