docs: add dartdoc categories, topic pages, and generation script

Add `dartdoc_options.yaml` to dart_monty, dart_monty_platform_interface,
and dart_monty_bridge with category definitions (Core, Execution, Errors,
Configuration, Sessions for the core packages; Bridge, Host Functions,
Plugins, Events for bridge).

Add `{@category}` tags to all 45+ public types so they appear grouped
in the generated docs sidebar. Improve library-level doc comments with
key types tables and ecosystem navigation. Hide internal SPI libraries
from public docs via `exclude`. Add `tool/dartdoc.sh` for local doc
generation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: runyaga

dartdoc_options.yaml

@@ -0,0 +1,18 @@
+dartdoc:
+  categories:
+    "Core":
+      markdown: doc/categories/core.md
+    "Execution":
+      markdown: doc/categories/execution.md
+    "Errors":
+      markdown: doc/categories/errors.md
+    "Configuration":
+      markdown: doc/categories/configuration.md
+    "Sessions":
+      markdown: doc/categories/sessions.md
+  categoryOrder:
+    - "Core"
+    - "Execution"
+    - "Errors"
+    - "Configuration"
+    - "Sessions"

doc/categories/configuration.md

@@ -0,0 +1 @@
+Resource limits, usage statistics, and stack frame data.

doc/categories/core.md

@@ -0,0 +1 @@
+The main entry point for running Python code. Start here with `Monty` and `MontyResult`.

doc/categories/errors.md

@@ -0,0 +1 @@
+Sealed error hierarchy for exhaustive error handling via pattern matching.

doc/categories/execution.md

@@ -0,0 +1 @@
+Types for iterative (multi-step) execution with external functions via `start()` / `resume()`.

doc/categories/sessions.md

@@ -0,0 +1 @@
+Stateful execution sessions and cancellation tokens.

lib/dart_monty.dart

@@ -1,7 +1,10 @@
 /// Pure Dart bindings for the Monty sandboxed Python interpreter.
 ///
-/// Backend is selected at compile time via conditional imports:
-/// native FFI on desktop/server, WASM in browsers. No Flutter required.
+/// This is the main entry point for running sandboxed Python from Dart.
+/// The backend (native FFI or browser WASM) is selected at compile time
+/// via conditional imports — no Flutter required.
+///
+/// ## Quick Start
 ///
 /// ```dart
 /// import 'package:dart_monty/dart_monty.dart';
@@ -11,6 +14,22 @@
 /// print(result.value); // 4
 /// await monty.dispose();
 /// ```
+///
+/// ## Key Types
+///
+/// - [Monty] — create an interpreter and run Python code
+/// - [MontyResult] — the return value from [Monty.run]
+/// - [MontyProgress], [MontyPending], [MontyComplete] — iterative execution
+///   with external functions via [Monty.start] / [Monty.resume]
+/// - [MontyError] — sealed error hierarchy for exhaustive error handling
+/// - [MontyLimits] — resource constraints (time, memory, stack depth)
+/// - [MontySession] — stateful sessions that persist Python globals
+///
+/// ## Related Packages
+///
+/// - **dart_monty_bridge** — high-level bridge with host function dispatch,
+///   event streaming, and a plugin system. Install separately:
+///   `dart pub add dart_monty_bridge`
 library;
 
 export 'package:dart_monty_platform_interface/dart_monty_platform_interface.dart';

lib/src/monty.dart

@@ -3,6 +3,8 @@ import 'package:dart_monty_platform_interface/dart_monty_platform_interface.dart
 
 /// Monty sandboxed Python interpreter.
 ///
+/// {@category Core}
+///
 /// Uses compile-time conditional imports to select the backend:
 /// - Native (macOS, Linux, Windows): Rust FFI via `dart:ffi`
 /// - Web (browser): WASM via `dart:js_interop`

packages/dart_monty_bridge/dartdoc_options.yaml

@@ -0,0 +1,17 @@
+dartdoc:
+  categories:
+    "Bridge":
+      markdown: doc/categories/bridge.md
+    "Host Functions":
+      markdown: doc/categories/host_functions.md
+    "Plugins":
+      markdown: doc/categories/plugins.md
+    "Events":
+      markdown: doc/categories/events.md
+  categoryOrder:
+    - "Bridge"
+    - "Host Functions"
+    - "Plugins"
+    - "Events"
+  exclude:
+    - "bridge_internals"

packages/dart_monty_bridge/doc/categories/bridge.md

@@ -0,0 +1 @@
+High-level bridge that wraps the start/resume loop and emits a stream of events.