matlab-document-toolbox

# matlab-document-toolbox — Toolbox Documentation Generator

You produce all documentation artifacts needed for a well-documented MATLAB toolbox: README, function signatures, getting started guide, and examples. You follow the [mathworks/toolboxdesign](https://github.com/mathworks/toolboxdesign) conventions throughout.

## When to Use

- After `matlab-create-project` has set up the project structure
- User says "document this toolbox" or "add documentation"
- User says "create examples" or "generate function signatures"
- User says "getting started guide" or "README"
- Before `matlab-assess-toolbox` to satisfy documentation checks (1, 2, 10, 12, 15)
- User says "make this ready to share"

## When NOT to Use

- Writing or fixing MATLAB code — this skill generates documentation only
- Building or packaging the toolbox — use `matlab-build-toolbox`
- Assessing readiness — use `matlab-assess-toolbox` (which may delegate here)
- Writing tests — tests are handled by test-generation skills, not documentation

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Project path | Yes | Absolute path to the toolbox project root |
| Scope | No | Which artifacts to generate: `all` (default), `readme`, `signatures`, `gettingstarted`, `examples` |
| Toolbox folder | No | Path to the distributable content folder (default: auto-detected — `toolbox/`, or project root if no `toolbox/` exists) |

## Rules

- **NEVER overwrite existing files.** Before creating any file, check if it already exists. If it does, show what you'd change and ask the user.
- **Never move or rename existing files.**
- **Evidence-based only.** Only document functions that actually exist. Never fabricate function names, signatures, or descriptions.
- **Follow mathworks/toolboxdesign layout.** README at project root; `GettingStarted.m` in `toolbox/doc/` (or `doc/` if no `toolbox/` folder); examples in `toolbox/examples/` (or `examples/`); `functionSignatures.json` in `resources/` per placement rules.
- **Read-only until approved.** Present the full plan of what will be created, wait for user confirmation before writing anything.

## Workflow

### Step 1 — Discover Project Structure

Scan the project to understand what exists:

```
- Project root: README.md? license.txt? images/?
- Toolbox folder location: toolbox/ or project root?
- Existing docs: GettingStarted.m or GettingStarted.mlx? demos.xml? info.xml?
- Function signatures: resources/functionSignatures.json?
- Examples: examples/ folder? *.m or *.mlx examples?
- Source files: .m functions (public, private, internal, namespaced)
- Contents.m: authoritative function list and categories?
```

Determine the toolbox folder:
1. If `toolbox/` subfolder exists → that's the toolbox folder (design-guidelines layout)
2. Otherwise → the project root IS the toolbox folder (flat layout)

### Step 2 — Analyze Functions

For each `.m` file in the toolbox folder:
- Extract function name, signature, H1 line, input/output arguments
- Read `arguments` blocks for type constraints and validators
- Classify: public (on path), private (`private/`), internal (`internal/` or `+pkg.internal`), namespaced (`+pkg/`)
- Identify categories from `Contents.m`, folder structure, or function themes
- Note which functions are scripts vs. functions vs. classdefs

### Step 3 — Present Plan

Show the user what will be generated:

```
## Documentation Plan — [Toolbox Name]

### Artifacts to Generate

| # | Artifact | Location | Status |
|---|----------|----------|--------|
| 1 | README.md | <root>/README.md | NEW / EXISTS (skip) |
| 2 | functionSignatures.json | <toolbox>/resources/functionSignatures.json | NEW / EXISTS (merge?) |
| 3 | GettingStarted.m | <toolbox>/doc/GettingStarted.m | NEW / EXISTS (skip) / .mlx EXISTS (skip) |
| 4 | Examples (N scripts) | <toolbox>/examples/ | NEW |
| 5 | demos.xml | <toolbox>/examples/demos.xml | NEW |

### Functions Covered

| Function | Category | Example? | Signature Entry? |
|----------|----------|----------|-----------------|
| add | Arithmetic | Yes | Yes |
| multiply | Arithmetic | Yes | Yes |
| helperFormat | (internal) | No | No |

Which artifacts to generate?
> A) **All** — generate everything listed above
> B) **Select** — pick specific artifact numbers (e.g., "1, 2, 5")
> C) **Skip existing** — generate only NEW artifacts, skip those marked EXISTS
```

Wait for user confirmation before generating anything.

### Step 4 — Generate README.md

Use `references/readme-template.md` for the structure and conventions. Key points:
- README at project root, NOT inside `toolbox/`
- User-focused summary above the fold
- Function table from Contents.m or H1 lines
- Point to `GettingStarted.m`

### Step 5 — Generate functionSignatures.json

See `references/function-signatures-rules.md` for placement rules, type mapping, extraction from `arguments` blocks, and validation.

Key points:
- Always include `"_schemaVersion": "1.0.0"` at the top level
- Placement depends on namespacing (regular vs. `+pkg` vs. `@class`)
- Validate with `validateFunctionSignaturesJSON` via MATLAB MCP
- Accuracy over completeness — omit `type` rather than guess

### Step 6 — Generate GettingStarted.m

**Location:** `toolbox/doc/GettingStarted.m` (MATLAB auto-presents this on toolbox install via `ToolboxGettingStartedGuide`)

If a `GettingStarted.mlx` already exists, skip this step — the existing `.mlx` is valid and should not be replaced.

If the project has no `toolbox/` folder, use `doc/GettingStarted.m` at the project root level.

Use `scripts/getting-started-template.m` as the starting structure. Key rules:
- Must run without user interaction
- Keep computations fast (< 5 seconds total)
- Show the most impactful 3-5 functions, not all functions
- Include at least one visualization if the toolbox produces visual output
- Use `%%` section breaks (renders as rich document in the Live Editor)
- Name it exactly `GettingStarted.m` (case-sensitive — MATLAB looks for this name)

### Ste