Add doc-weaver: TypeScript documentation compiler
TypeDoc + JSDoc (RDFC) compiler mirroring doc-forge. Emits a doc-forge-shaped MCP JSON bundle and a TypeDoc human site, with an MCP server (official SDK, stdio), a build/serve CLI, and React-aware kind classification. Includes the RDFC wiki (docs/wiki) and MkDocs config.
This commit is contained in:
60
docs/wiki/01_overview.md
Normal file
60
docs/wiki/01_overview.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Library Overview
|
||||
|
||||
`doc-weaver` turns RDFC-compliant TypeScript JSDoc into maintainable reference
|
||||
documentation. It never edits source comments; it reads them, renders them, and
|
||||
assembles documentation from all available material — exactly as `doc-forge`
|
||||
does for Python docstrings.
|
||||
|
||||
Analysis is static: source is parsed by the TypeScript compiler API via TypeDoc
|
||||
and is never executed.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Which Build Should You Use?
|
||||
|
||||
| Flag | Source | Output |
|
||||
|-----------------------|-----------------------|---------------------------------------------------|
|
||||
| `--docs` (`--mkdocs`, `--lib`) | JSDoc comments | `site/lib/**` TypeDoc HTML (the MkDocs parallel) |
|
||||
| `--mcp` | JSDoc comments + model | `docs/mcp/**` doc-forge-shaped JSON |
|
||||
| `--api` | OpenAPI spec | reserved |
|
||||
| `--wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
TypeScript + JSDoc
|
||||
|
|
||||
TypeDoc (loader) -> serialized reflection JSON
|
||||
|
|
||||
TypeDocJsonToMCP (renderer) -> MCP bundle (docs/mcp/)
|
||||
generateHumanDocs (renderer) -> TypeDoc HTML site (site/lib/)
|
||||
```
|
||||
|
||||
The MCP renderer and the human renderer never depend on each other: both read
|
||||
the same serialized reflections, so the machine bundle and the human site can
|
||||
never disagree about a symbol.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 MCP bundle shape
|
||||
|
||||
`docs/mcp/**` is a self-contained, machine-readable reference whose shape is
|
||||
byte-compatible with `doc-forge`:
|
||||
|
||||
```
|
||||
docs/mcp/
|
||||
index.json { project, type: "docforge-model", modules_count, source }
|
||||
nav.json [ { module, resource: "docs://modules/<module>" } ]
|
||||
modules/<module>.json { module, content: { path, docstring, objects } }
|
||||
```
|
||||
|
||||
`doc-weaver serve --mcp --module doc-weaver` serves it over stdio. See the
|
||||
[RDFC Guide](02_rdfc.md) for how to write the JSDoc that fills it.
|
||||
|
||||
---
|
||||
|
||||
## ➡️ Read Next
|
||||
|
||||
- [02 – RDFC Guide](02_rdfc.md)
|
||||
173
docs/wiki/02_rdfc.md
Normal file
173
docs/wiki/02_rdfc.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# RDFC Guide
|
||||
|
||||
RDFC — the **React Doc-forge Convention** — is the TypeScript counterpart to
|
||||
doc-forge's **GSDFC**. This page is the practical companion to the convention:
|
||||
how to write JSDoc so it renders correctly in the TypeDoc site **and** stays
|
||||
machine-parsable in the MCP bundle and by AI tooling.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Overview
|
||||
|
||||
- Documentation is the single source of truth and lives in JSDoc comments.
|
||||
- `doc-weaver` compiles comments; it never rewrites or invents them.
|
||||
- Structure follows the TypeScript export hierarchy.
|
||||
- Every public export should have a complete and accurate JSDoc comment.
|
||||
- Types live in signatures; do not duplicate them in prose unless a tag
|
||||
requires it.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Module (file) level
|
||||
|
||||
Document the file with a leading block comment. It becomes the module
|
||||
`docstring` in the MCP bundle.
|
||||
|
||||
```ts
|
||||
/**
|
||||
* # Resource list
|
||||
*
|
||||
* Renders, filters, and paginates a resource collection.
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* Notes:
|
||||
* - Reads configuration from the OpenAPI spec.
|
||||
* - Pagination is server-driven.
|
||||
*/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Components
|
||||
|
||||
Document the component function and its props. Components are classified
|
||||
automatically as `kind: "component"` (PascalCase name).
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Render a single resource row with actions.
|
||||
*
|
||||
* @param props - Component props.
|
||||
* @param props.item - The resource record to display.
|
||||
* @param props.onSelect - Invoked when the row is selected.
|
||||
* @returns The rendered row element.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ResourceList item={record} onSelect={handleSelect} />
|
||||
* ```
|
||||
*/
|
||||
export function ResourceList(props: ListCellProps) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Hooks
|
||||
|
||||
Hooks are classified automatically as `kind: "hook"` (name starts with `use`).
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Subscribe to server-sent events for an item.
|
||||
*
|
||||
* @param url - SSE endpoint, or `null` to disable.
|
||||
* @param handlers - Event handlers keyed by event name.
|
||||
* @returns Connection state and the latest payload.
|
||||
*
|
||||
* @remarks
|
||||
* The subscription is torn down on unmount.
|
||||
*/
|
||||
export function useItemSse(url: string | null, handlers: ItemSseHandlers) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Types, interfaces, and members
|
||||
|
||||
Document the type and each member. Members become nested `members` entries in
|
||||
the MCP bundle.
|
||||
|
||||
```ts
|
||||
/**
|
||||
* A single display field extracted from an OpenAPI schema.
|
||||
*/
|
||||
export interface FieldConfig {
|
||||
/** Property name in the payload. */
|
||||
name: string;
|
||||
/** `x-edit-as: date` — edit a `date-time` field with a date input. */
|
||||
editAs?: string;
|
||||
/** Schema-level `default` used to seed create-form state. */
|
||||
defaultValue?: unknown;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Notes subsection grouping
|
||||
|
||||
Group related information using labeled subsections (Markdown bold):
|
||||
|
||||
```
|
||||
Notes:
|
||||
**Guarantees:**
|
||||
|
||||
- deterministic output
|
||||
|
||||
**Lifecycle:**
|
||||
|
||||
- created during initialization
|
||||
- reused across renders
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Heading map
|
||||
|
||||
`doc-weaver` renders JSDoc block tags into stable markdown headings so both
|
||||
TypeDoc and the MCP bundle agree:
|
||||
|
||||
| JSDoc tag | Rendered heading |
|
||||
|-----------|------------------|
|
||||
| `@param` | `**Parameters:**` |
|
||||
| `@returns` / `@return` | `**Returns:**` |
|
||||
| `@throws` | `**Throws:**` |
|
||||
| `@example` | `**Example:**` |
|
||||
| `@deprecated` | `**Deprecated:**` |
|
||||
| `@see` | `**See also:**` |
|
||||
| `@remarks` | `**Remarks:**` |
|
||||
| *other* | `**@tag:**` |
|
||||
|
||||
---
|
||||
|
||||
## 📦 Mapping to output kinds
|
||||
|
||||
| TS construct | `kind` |
|
||||
|--------------|--------|
|
||||
| interface / type alias | `interface` / `type-alias` |
|
||||
| function component (PascalCase) | `component` |
|
||||
| custom hook (`use*`) | `hook` |
|
||||
| plain function | `function` |
|
||||
| object / class member | `property` / `method` |
|
||||
| const / let / var | `variable` |
|
||||
|
||||
An explicit `@kind` tag overrides the inferred kind.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Enforcement
|
||||
|
||||
Unlike doc-forge (which runs `pydoclint` in CI), `doc-weaver` performs no
|
||||
signature linting: TypeDoc extracts whatever JSDoc is present. Keep comments
|
||||
complete and accurate — they are the single source of truth for both the human
|
||||
site and the machine bundle.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [01 – Overview](01_overview.md)
|
||||
55
docs/wiki/index.md
Normal file
55
docs/wiki/index.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# 🪡 doc-weaver — TypeScript Documentation Weaver
|
||||
|
||||
`doc-weaver` is the TypeScript counterpart to `doc-forge`. It compiles
|
||||
JSDoc-annotated TypeScript into a **TypeDoc** site (the MkDocs parallel) and a
|
||||
**doc-forge-shaped MCP JSON bundle**, so React packages document themselves for
|
||||
humans and agents alike.
|
||||
|
||||
> **Doc model:** this wiki is written for humans — guides and conventions. The
|
||||
> authoritative API contracts live in the code (JSDoc) and the machine-readable
|
||||
> bundle under `docs/mcp/`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Key Features
|
||||
|
||||
- 🧵 JSDoc extraction via TypeDoc (the TypeScript compiler API)
|
||||
- 🧬 doc-forge-compatible MCP bundle (`index.json`, `nav.json`, `modules/*.json`)
|
||||
- ⚛️ React-aware kinds — `component` (PascalCase) and `hook` (`use*`)
|
||||
- 📚 RDFC (React Doc-forge Convention) — the JSDoc parallel to GSDFC
|
||||
- 🔌 MCP server over stdio exposing `docs://index`, `docs://nav`, and
|
||||
`docs://modules/{module}`
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
This produces the `doc-weaver` binary under `bin/` and `dist/`.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Documentation Structure
|
||||
|
||||
| Section | Description |
|
||||
|-----------------------------------------|------------------------------------------------|
|
||||
| [Overview](01_overview.md) | What doc-weaver is and how it fits |
|
||||
| [RDFC Guide](02_rdfc.md) | How to write RDFC-conformant JSDoc |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Resources
|
||||
|
||||
- **Source Code:** the `doc-weaver` repository
|
||||
- **MCP Bundle:** generated by `doc-weaver build --mcp --module src/index.ts`
|
||||
into `docs/mcp/`
|
||||
- **Library Registry:** registered in the standards hub as `doc-weaver`
|
||||
(MCP `:8010`)
|
||||
|
||||
---
|
||||
|
||||
© Aetoskia Internal — `doc-weaver` 0.1.0
|
||||
Reference in New Issue
Block a user