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:
186
README.md
Normal file
186
README.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# doc-weaver
|
||||
|
||||
TypeScript documentation compiler that mirrors [`doc-forge`](../doc-forge).
|
||||
|
||||
`doc-weaver` reads **TypeScript + JSDoc** and emits documentation for both
|
||||
humans and machines:
|
||||
|
||||
- **Humans** – a [TypeDoc](https://typedoc.org) site (the parallel to
|
||||
doc-forge's MkDocs site).
|
||||
- **Machines** – an MCP JSON bundle (`index.json`, `nav.json`, `modules/`)
|
||||
whose shape is byte-compatible with the bundle `doc-forge` produces for
|
||||
Python, so the same consumers (agents, `docs://` clients, the standards
|
||||
registry) can query it unchanged.
|
||||
|
||||
Where `doc-forge` uses `mkdocs` + Google-style docstrings (`GSDFC`),
|
||||
`doc-weaver` uses `TypeDoc` + Google-style JSDoc (`RDFC`).
|
||||
|
||||
---
|
||||
|
||||
## Parity map
|
||||
|
||||
| Concern | Python (`doc-forge`) | TypeScript (`doc-weaver`) |
|
||||
| --- | --- | --- |
|
||||
| Source of truth | Python docstrings (GSDFC) | TypeScript types + JSDoc (RDFC) |
|
||||
| Front-end (loader) | Griffe static analysis | TypeDoc (TypeScript compiler API) |
|
||||
| Middle-end (model) | `Project -> Module -> DocObject` | `Project -> Module -> DocObject` |
|
||||
| Human renderer | MkDocs (`site/lib`) | TypeDoc (`site/lib`) |
|
||||
| Machine renderer | `MCPRenderer` JSON | `TypeDocJsonToMCP` JSON |
|
||||
| Convention | GSDFC (Google-style docstrings) | RDFC (Google-style JSDoc) |
|
||||
| CLI | `doc-forge build/serve` | `doc-weaver build/serve` |
|
||||
| MCP server | `docforge.servers.MCPServer` | `docweaver.servers.MCPServer` |
|
||||
|
||||
### MCP bundle (identical shape to 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 } }
|
||||
```
|
||||
|
||||
Each object is rendered recursively as:
|
||||
|
||||
```
|
||||
{ name, kind, path, signature, docstring, members? }
|
||||
```
|
||||
|
||||
Resource URIs use the same `docs://` scheme as doc-forge:
|
||||
|
||||
- `docs://index`
|
||||
- `docs://nav`
|
||||
- `docs://modules/{module}`
|
||||
|
||||
Module paths use **dotted** form (`components.ResourceList`) so a single URI
|
||||
segment matches, exactly like Python's dotted module paths.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
This produces the `doc-weaver` binary in `dist/` and `bin/`.
|
||||
|
||||
---
|
||||
|
||||
## CLI usage
|
||||
|
||||
```bash
|
||||
# Machine-readable MCP JSON
|
||||
doc-weaver build --mcp --module src/index.ts --project-name my-app
|
||||
|
||||
# Human-facing TypeDoc site (MkDocs parallel)
|
||||
doc-weaver build --docs --module src/index.ts --project-name my-app
|
||||
|
||||
# Both in one pass
|
||||
doc-weaver build --mcp --docs --module src/index.ts
|
||||
|
||||
# Serve a generated MCP bundle
|
||||
doc-weaver serve --mcp --module my-app --out-dir docs/mcp
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
| Flag | Meaning | Default |
|
||||
| --- | --- | --- |
|
||||
| `--mcp` | Emit MCP JSON bundle | – |
|
||||
| `--docs` / `--mkdocs` / `--lib` | Emit the TypeDoc human site | – |
|
||||
| `--module <path>` / `--entry <file>` | Entry point for TypeDoc | required |
|
||||
| `--project-name <name>` / `--name <name>` | Project name | `package.json` name |
|
||||
| `--tsconfig <file>` | tsconfig to use | auto-discovered |
|
||||
| `--out-dir <dir>` | MCP output directory | `docs/mcp` |
|
||||
| `--out <dir>` | Human docs output directory | `site/lib` |
|
||||
| `--plugin <name...>` | Extra TypeDoc plugins | – |
|
||||
| `--strict` | Fail on TypeScript errors instead of generating anyway | off |
|
||||
|
||||
By default doc-weaver **skips TypeScript error checking** (`skipErrorChecking`),
|
||||
so documentation is produced even when a project has unrelated type errors.
|
||||
Pass `--strict` to make errors fatal.
|
||||
|
||||
`--api` and `--wiki` are reserved for parity with doc-forge and are not yet
|
||||
implemented.
|
||||
|
||||
---
|
||||
|
||||
## Adding it to a React package
|
||||
|
||||
Add a script to the package's `package.json` (pointing at the package entry):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"scripts": {
|
||||
"docs:mcp": "doc-weaver build --mcp --module index.ts --out-dir docs/mcp",
|
||||
"docs:site": "doc-weaver build --docs --module index.ts --out site/lib",
|
||||
"docs:serve": "doc-weaver serve --mcp --module my-app --out-dir docs/mcp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Packages in this workspace (`react-openapi`, `react-auth`, `vet`) export their
|
||||
public surface from `index.ts`, so a single `--module index.ts` documents the
|
||||
package. To document **per-file modules**, pass a directory or several entry
|
||||
points instead:
|
||||
|
||||
```bash
|
||||
doc-weaver build --mcp --module src
|
||||
doc-weaver build --mcp --module src/a.ts --module src/b.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
TypeScript + JSDoc
|
||||
|
|
||||
TypeDoc (loader) -> serialized reflection JSON
|
||||
|
|
||||
TypeDocJsonToMCP (renderer) -> MCP bundle
|
||||
generateHumanDocs (renderer)-> TypeDoc HTML site
|
||||
```
|
||||
|
||||
```
|
||||
src/
|
||||
cli/ commands, mcp-utils
|
||||
loaders/ typedoc-loader (static analysis)
|
||||
models/ semantic model + TypeDoc helpers
|
||||
renderers/ mcp-renderer, human-docs, docstring, signature
|
||||
servers/ mcp-server (official MCP SDK)
|
||||
templates/ typedoc.json baseline
|
||||
```
|
||||
|
||||
Like doc-forge, `doc-weaver` is renderer-agnostic: the MCP renderer and the
|
||||
TypeDoc renderer never depend on each other, and no user code is executed to
|
||||
produce documentation semantics.
|
||||
|
||||
---
|
||||
|
||||
## Convention (RDFC)
|
||||
|
||||
See [`docs/wiki/02_rdfc.md`](docs/wiki/02_rdfc.md) for the *React Doc-forge
|
||||
Convention* (RDFC) — Google-style JSDoc that keeps docstrings the single source
|
||||
of truth and makes them machine-parsable.
|
||||
|
||||
The hand-written docs live under `docs/wiki/` and are built with MkDocs into
|
||||
`site/wiki/` (mirroring doc-forge), while the API site is built by TypeDoc into
|
||||
`site/lib/`:
|
||||
|
||||
```bash
|
||||
# Wiki (MkDocs) -> site/wiki/
|
||||
mkdocs build -f docs/mkdocs.wiki.yml
|
||||
|
||||
# API site (TypeDoc) + MCP bundle for doc-weaver itself
|
||||
node bin/doc-weaver.js build --mcp --docs \
|
||||
--module src --project-name doc-weaver \
|
||||
--out-dir docs/mcp --out site/lib
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user