@dogsbay/plugin-typedoc 0.2.0-beta.81
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +120 -0
- package/dist/index.js.map +1 -0
- package/dist/reflect.d.ts +34 -0
- package/dist/reflect.d.ts.map +1 -0
- package/dist/reflect.js +126 -0
- package/dist/reflect.js.map +1 -0
- package/dist/render.d.ts +29 -0
- package/dist/render.d.ts.map +1 -0
- package/dist/render.js +67 -0
- package/dist/render.js.map +1 -0
- package/dist/schema.d.ts +40 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +54 -0
- package/dist/schema.js.map +1 -0
- package/package.json +47 -0
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @dogsbay/plugin-typedoc
|
|
2
|
+
|
|
3
|
+
Generate API-reference pages from a TypeScript project for a
|
|
4
|
+
Dogsbay docs site.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
pnpm add @dogsbay/plugin-typedoc
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Use
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
# dogsbay.config.yml
|
|
16
|
+
plugins:
|
|
17
|
+
- "@dogsbay/plugin-typedoc"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
With options:
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
plugins:
|
|
24
|
+
- name: "@dogsbay/plugin-typedoc"
|
|
25
|
+
options:
|
|
26
|
+
tsconfig: "./tsconfig.json"
|
|
27
|
+
output: "api"
|
|
28
|
+
sidebarLabel: "API Reference"
|
|
29
|
+
entryPoints:
|
|
30
|
+
- "./src/public.ts"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Options
|
|
34
|
+
|
|
35
|
+
| Option | Default | Description |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `tsconfig` | `"./tsconfig.json"` | Path to the TypeScript project's tsconfig. |
|
|
38
|
+
| `output` | `"api"` | URL segment under which generated pages live. |
|
|
39
|
+
| `sidebarLabel` | `"API Reference"` | Label of the generated nav group. |
|
|
40
|
+
| `entryPoints` | (all) | Restrict to a list of files. Defaults to every TS source in the program. |
|
|
41
|
+
|
|
42
|
+
## How it works
|
|
43
|
+
|
|
44
|
+
1. **Build time** — the plugin reads your tsconfig, instantiates a
|
|
45
|
+
TypeScript program, and walks every exported declaration in
|
|
46
|
+
the project's source files. Each export becomes a Dogsbay
|
|
47
|
+
`ExportPage` with the symbol's name, JSDoc comment, signature,
|
|
48
|
+
and a source-file pointer.
|
|
49
|
+
|
|
50
|
+
2. **Nav** — appends an `API Reference` sidebar group with one
|
|
51
|
+
entry per generated page.
|
|
52
|
+
|
|
53
|
+
3. **Audit** — registers a `typedoc/missing-doc` rule. Run
|
|
54
|
+
`dogsbay site check` and any export without a JSDoc comment
|
|
55
|
+
is flagged.
|
|
56
|
+
|
|
57
|
+
## What this plugin demonstrates
|
|
58
|
+
|
|
59
|
+
This is the second reference Dogsbay plugin (the first is
|
|
60
|
+
`@dogsbay/plugin-image-zoom`). Together they exercise the
|
|
61
|
+
external-schema-to-page-tree mechanic that an OpenAPI plugin
|
|
62
|
+
would also use — built-in OpenAPI rendering uses the same lifecycle
|
|
63
|
+
hooks described in `plans/plugin-api.md`.
|
|
64
|
+
|
|
65
|
+
## License
|
|
66
|
+
|
|
67
|
+
MIT.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { DogsbayPlugin } from "@dogsbay/types";
|
|
2
|
+
import { type TypedocOptions } from "./schema.js";
|
|
3
|
+
export type { TypedocOptions } from "./schema.js";
|
|
4
|
+
export { reflectProject } from "./reflect.js";
|
|
5
|
+
export { reflectionsToPages } from "./render.js";
|
|
6
|
+
export default function typedocPlugin(input?: TypedocOptions): DogsbayPlugin;
|
|
7
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAIhE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,aAAa,CAwF3E"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@dogsbay/plugin-typedoc` — generates API-reference pages from
|
|
3
|
+
* a TypeScript project.
|
|
4
|
+
*
|
|
5
|
+
* Demonstrates the "external schema → generated page tree + nav
|
|
6
|
+
* + audit rule" mechanic. Same shape an OpenAPI plugin would use:
|
|
7
|
+
*
|
|
8
|
+
* - extendConfig: kicks off TS reflection (cached on the
|
|
9
|
+
* factory closure so repeated hooks share it)
|
|
10
|
+
* - onContentImported: injects pages into the page set
|
|
11
|
+
* - transformNav: appends the API-reference sidebar group
|
|
12
|
+
* - auditRules: flags reflections missing JSDoc descriptions
|
|
13
|
+
*
|
|
14
|
+
* Usage:
|
|
15
|
+
*
|
|
16
|
+
* # dogsbay.config.yml
|
|
17
|
+
* plugins:
|
|
18
|
+
* - name: "@dogsbay/plugin-typedoc"
|
|
19
|
+
* options:
|
|
20
|
+
* tsconfig: "./tsconfig.json"
|
|
21
|
+
* output: "api"
|
|
22
|
+
*/
|
|
23
|
+
import path from "node:path";
|
|
24
|
+
import { parseOptions } from "./schema.js";
|
|
25
|
+
import { reflectProject } from "./reflect.js";
|
|
26
|
+
import { reflectionsToPages } from "./render.js";
|
|
27
|
+
export { reflectProject } from "./reflect.js";
|
|
28
|
+
export { reflectionsToPages } from "./render.js";
|
|
29
|
+
export default function typedocPlugin(input) {
|
|
30
|
+
const opts = parseOptions(input);
|
|
31
|
+
// Closure-scoped cache so onContentImported, transformNav, and
|
|
32
|
+
// auditRules all see the same reflection set without
|
|
33
|
+
// re-parsing the TS project three times.
|
|
34
|
+
let cached = null;
|
|
35
|
+
function getReflections(ctx) {
|
|
36
|
+
if (cached !== null)
|
|
37
|
+
return cached;
|
|
38
|
+
const tsconfigAbs = path.isAbsolute(opts.tsconfig)
|
|
39
|
+
? opts.tsconfig
|
|
40
|
+
: path.resolve(ctx.siteRoot, opts.tsconfig);
|
|
41
|
+
const result = reflectProject({
|
|
42
|
+
tsconfigPath: tsconfigAbs,
|
|
43
|
+
entryPoints: opts.entryPoints?.map((p) => path.isAbsolute(p) ? p : path.resolve(ctx.siteRoot, p)),
|
|
44
|
+
});
|
|
45
|
+
for (const d of result.diagnostics)
|
|
46
|
+
ctx.logger.warn(d);
|
|
47
|
+
cached = result.reflections;
|
|
48
|
+
return cached;
|
|
49
|
+
}
|
|
50
|
+
return {
|
|
51
|
+
name: "@dogsbay/plugin-typedoc",
|
|
52
|
+
onContentImported(pages, nav, ctx) {
|
|
53
|
+
const reflections = getReflections(ctx);
|
|
54
|
+
const { pages: newPages } = reflectionsToPages({
|
|
55
|
+
reflections,
|
|
56
|
+
output: opts.output,
|
|
57
|
+
sidebarLabel: opts.sidebarLabel,
|
|
58
|
+
});
|
|
59
|
+
return { pages: [...pages, ...newPages], nav };
|
|
60
|
+
},
|
|
61
|
+
transformNav(nav, ctx) {
|
|
62
|
+
const reflections = getReflections(ctx);
|
|
63
|
+
if (reflections.length === 0)
|
|
64
|
+
return nav;
|
|
65
|
+
const { navGroup } = reflectionsToPages({
|
|
66
|
+
reflections,
|
|
67
|
+
output: opts.output,
|
|
68
|
+
sidebarLabel: opts.sidebarLabel,
|
|
69
|
+
});
|
|
70
|
+
return [...nav, navGroup];
|
|
71
|
+
},
|
|
72
|
+
auditRules(ctx) {
|
|
73
|
+
// Populate the cache here too — `site check` creates a
|
|
74
|
+
// fresh plugin instance per invocation, so we can't rely on
|
|
75
|
+
// a build having already filled the cache. Calling
|
|
76
|
+
// getReflections() is idempotent (it short-circuits on the
|
|
77
|
+
// second call within a single instance).
|
|
78
|
+
getReflections(ctx);
|
|
79
|
+
return [
|
|
80
|
+
{
|
|
81
|
+
id: "typedoc/missing-doc",
|
|
82
|
+
category: "typedoc",
|
|
83
|
+
stage: "source",
|
|
84
|
+
severity: "warning",
|
|
85
|
+
description: "TypeScript export missing JSDoc description.",
|
|
86
|
+
run: (rawCtx) => {
|
|
87
|
+
// Only fire on pages this plugin produced. Match by
|
|
88
|
+
// slug prefix.
|
|
89
|
+
const sourceCtx = rawCtx;
|
|
90
|
+
const page = sourceCtx.page;
|
|
91
|
+
if (!page.slug.startsWith(`${opts.output}/`))
|
|
92
|
+
return [];
|
|
93
|
+
const refl = (cached ?? []).find((r) => `${opts.output}/${slugifyName(r.name)}` === page.slug);
|
|
94
|
+
if (!refl)
|
|
95
|
+
return [];
|
|
96
|
+
if (refl.doc.trim() === "") {
|
|
97
|
+
return [
|
|
98
|
+
{
|
|
99
|
+
ruleId: "typedoc/missing-doc",
|
|
100
|
+
severity: "warning",
|
|
101
|
+
file: page.slug,
|
|
102
|
+
message: `Exported ${refl.kind} \`${refl.name}\` has no JSDoc description.`,
|
|
103
|
+
context: `${refl.sourceFile}:${refl.line}`,
|
|
104
|
+
},
|
|
105
|
+
];
|
|
106
|
+
}
|
|
107
|
+
return [];
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
];
|
|
111
|
+
},
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
function slugifyName(name) {
|
|
115
|
+
return name
|
|
116
|
+
.replace(/[A-Z]+/g, (m) => m.toLowerCase())
|
|
117
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
118
|
+
.replace(/^-+|-+$/g, "");
|
|
119
|
+
}
|
|
120
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,OAAO,EAAE,YAAY,EAAuB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,cAAc,EAAmB,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAsB;IAC1D,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEjC,+DAA+D;IAC/D,qDAAqD;IACrD,yCAAyC;IACzC,IAAI,MAAM,GAAwB,IAAI,CAAC;IACvC,SAAS,cAAc,CAAC,GAAyB;QAC/C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;YAChD,CAAC,CAAC,IAAI,CAAC,QAAQ;YACf,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,cAAc,CAAC;YAC5B,YAAY,EAAE,WAAW;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACvC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CACvD;SACF,CAAC,CAAC;QACH,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,WAAW;YAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,IAAI,EAAE,yBAAyB;QAE/B,iBAAiB,CAAC,KAAmB,EAAE,GAAc,EAAE,GAAG;YACxD,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;YACxC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,kBAAkB,CAAC;gBAC7C,WAAW;gBACX,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC,CAAC,CAAC;YACH,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,GAAG,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjD,CAAC;QAED,YAAY,CAAC,GAAc,EAAE,GAAG;YAC9B,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;YACxC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC;YACzC,MAAM,EAAE,QAAQ,EAAE,GAAG,kBAAkB,CAAC;gBACtC,WAAW;gBACX,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAED,UAAU,CAAC,GAAG;YACZ,uDAAuD;YACvD,4DAA4D;YAC5D,mDAAmD;YACnD,2DAA2D;YAC3D,yCAAyC;YACzC,cAAc,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO;gBACL;oBACE,EAAE,EAAE,qBAAqB;oBACzB,QAAQ,EAAE,SAAS;oBACnB,KAAK,EAAE,QAAQ;oBACf,QAAQ,EAAE,SAAS;oBACnB,WAAW,EAAE,8CAA8C;oBAC3D,GAAG,EAAE,CAAC,MAAe,EAAE,EAAE;wBACvB,oDAAoD;wBACpD,eAAe;wBACf,MAAM,SAAS,GAAG,MAA8B,CAAC;wBACjD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;wBAC5B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC;4BAAE,OAAO,EAAE,CAAC;wBACxD,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,IAAI,CAC7D,CAAC;wBACF,IAAI,CAAC,IAAI;4BAAE,OAAO,EAAE,CAAC;wBACrB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;4BAC3B,OAAO;gCACL;oCACE,MAAM,EAAE,qBAAqB;oCAC7B,QAAQ,EAAE,SAAkB;oCAC5B,IAAI,EAAE,IAAI,CAAC,IAAI;oCACf,OAAO,EAAE,YAAY,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,8BAA8B;oCAC3E,OAAO,EAAE,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,EAAE;iCAC3C;6BACF,CAAC;wBACJ,CAAC;wBACD,OAAO,EAAE,CAAC;oBACZ,CAAC;iBACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,IAAI;SACR,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC1C,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
export type ReflectionKind = "function" | "class" | "interface" | "type" | "variable" | "enum";
|
|
2
|
+
export interface Reflection {
|
|
3
|
+
/** Symbol name as exported. */
|
|
4
|
+
name: string;
|
|
5
|
+
kind: ReflectionKind;
|
|
6
|
+
/** JSDoc comment text, joined with line breaks; empty when missing. */
|
|
7
|
+
doc: string;
|
|
8
|
+
/** A short signature string (e.g. "(a: number, b: number): number"). */
|
|
9
|
+
signature?: string;
|
|
10
|
+
/** Source file path relative to the project root. */
|
|
11
|
+
sourceFile: string;
|
|
12
|
+
/** 1-based line number in the source file. */
|
|
13
|
+
line: number;
|
|
14
|
+
}
|
|
15
|
+
export interface ReflectProjectInput {
|
|
16
|
+
/** Absolute path to tsconfig.json. */
|
|
17
|
+
tsconfigPath: string;
|
|
18
|
+
/**
|
|
19
|
+
* Optional restricted entry-file list (absolute paths). When
|
|
20
|
+
* empty/undefined, every file in the program is scanned.
|
|
21
|
+
*/
|
|
22
|
+
entryPoints?: string[];
|
|
23
|
+
}
|
|
24
|
+
export interface ReflectProjectResult {
|
|
25
|
+
reflections: Reflection[];
|
|
26
|
+
/** Diagnostic messages from TS — surfaced as warnings, not errors. */
|
|
27
|
+
diagnostics: string[];
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Reflect a TypeScript project. Returns the list of exported
|
|
31
|
+
* declarations + non-fatal diagnostic strings.
|
|
32
|
+
*/
|
|
33
|
+
export declare function reflectProject(input: ReflectProjectInput): ReflectProjectResult;
|
|
34
|
+
//# sourceMappingURL=reflect.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../src/reflect.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,sEAAsE;IACtE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAoD/E"}
|
package/dist/reflect.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tiny TypeScript reflection layer.
|
|
3
|
+
*
|
|
4
|
+
* Uses the TypeScript compiler API to discover exported symbols
|
|
5
|
+
* in a project (functions, classes, interfaces, type aliases,
|
|
6
|
+
* variables) and pull their JSDoc text + signature for the
|
|
7
|
+
* docs page.
|
|
8
|
+
*
|
|
9
|
+
* This is intentionally smaller than full TypeDoc — the goal
|
|
10
|
+
* isn't to compete with TypeDoc but to demonstrate that the
|
|
11
|
+
* Dogsbay plugin API can carry "schema → page tree + nav +
|
|
12
|
+
* audit rule," which is the same mechanic an OpenAPI plugin
|
|
13
|
+
* would use. Real TypeDoc-quality output is a future polish.
|
|
14
|
+
*/
|
|
15
|
+
import ts from "typescript";
|
|
16
|
+
import path from "node:path";
|
|
17
|
+
/**
|
|
18
|
+
* Reflect a TypeScript project. Returns the list of exported
|
|
19
|
+
* declarations + non-fatal diagnostic strings.
|
|
20
|
+
*/
|
|
21
|
+
export function reflectProject(input) {
|
|
22
|
+
const { tsconfigPath, entryPoints } = input;
|
|
23
|
+
const projectDir = path.dirname(tsconfigPath);
|
|
24
|
+
// Read + parse tsconfig.json
|
|
25
|
+
const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
|
|
26
|
+
if (configFile.error) {
|
|
27
|
+
return {
|
|
28
|
+
reflections: [],
|
|
29
|
+
diagnostics: [`Failed to read ${tsconfigPath}: ${configFile.error.messageText}`],
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, projectDir);
|
|
33
|
+
const program = ts.createProgram({
|
|
34
|
+
rootNames: parsed.fileNames,
|
|
35
|
+
options: parsed.options,
|
|
36
|
+
});
|
|
37
|
+
const checker = program.getTypeChecker();
|
|
38
|
+
const allowedFiles = entryPoints && entryPoints.length > 0
|
|
39
|
+
? new Set(entryPoints.map((p) => path.resolve(p)))
|
|
40
|
+
: null;
|
|
41
|
+
const reflections = [];
|
|
42
|
+
const diagnostics = [];
|
|
43
|
+
for (const sourceFile of program.getSourceFiles()) {
|
|
44
|
+
if (sourceFile.isDeclarationFile)
|
|
45
|
+
continue;
|
|
46
|
+
if (allowedFiles && !allowedFiles.has(path.resolve(sourceFile.fileName)))
|
|
47
|
+
continue;
|
|
48
|
+
if (sourceFile.fileName.includes("node_modules"))
|
|
49
|
+
continue;
|
|
50
|
+
const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
|
|
51
|
+
if (!moduleSymbol)
|
|
52
|
+
continue;
|
|
53
|
+
const exports = checker.getExportsOfModule(moduleSymbol);
|
|
54
|
+
for (const sym of exports) {
|
|
55
|
+
const decl = sym.declarations?.[0];
|
|
56
|
+
if (!decl)
|
|
57
|
+
continue;
|
|
58
|
+
const reflection = describeSymbol(sym, decl, checker, projectDir);
|
|
59
|
+
if (reflection)
|
|
60
|
+
reflections.push(reflection);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
// Sort by name so output is deterministic across runs.
|
|
64
|
+
reflections.sort((a, b) => a.name.localeCompare(b.name));
|
|
65
|
+
return { reflections, diagnostics };
|
|
66
|
+
}
|
|
67
|
+
function describeSymbol(sym, decl, checker, projectDir) {
|
|
68
|
+
const name = sym.getName();
|
|
69
|
+
// Skip common synthetic exports.
|
|
70
|
+
if (name === "default" && !ts.isFunctionDeclaration(decl) && !ts.isClassDeclaration(decl)) {
|
|
71
|
+
// default export of a non-function/class — fall through
|
|
72
|
+
}
|
|
73
|
+
const kind = inferKind(decl);
|
|
74
|
+
if (!kind)
|
|
75
|
+
return undefined;
|
|
76
|
+
const doc = readJsDoc(sym, checker);
|
|
77
|
+
const signature = readSignature(sym, decl, checker);
|
|
78
|
+
const sourceFile = decl.getSourceFile();
|
|
79
|
+
const lineCol = sourceFile.getLineAndCharacterOfPosition(decl.getStart());
|
|
80
|
+
return {
|
|
81
|
+
name,
|
|
82
|
+
kind,
|
|
83
|
+
doc,
|
|
84
|
+
signature,
|
|
85
|
+
sourceFile: path.relative(projectDir, sourceFile.fileName),
|
|
86
|
+
line: lineCol.line + 1,
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
function inferKind(decl) {
|
|
90
|
+
if (ts.isFunctionDeclaration(decl))
|
|
91
|
+
return "function";
|
|
92
|
+
if (ts.isClassDeclaration(decl))
|
|
93
|
+
return "class";
|
|
94
|
+
if (ts.isInterfaceDeclaration(decl))
|
|
95
|
+
return "interface";
|
|
96
|
+
if (ts.isTypeAliasDeclaration(decl))
|
|
97
|
+
return "type";
|
|
98
|
+
if (ts.isVariableDeclaration(decl))
|
|
99
|
+
return "variable";
|
|
100
|
+
if (ts.isEnumDeclaration(decl))
|
|
101
|
+
return "enum";
|
|
102
|
+
return undefined;
|
|
103
|
+
}
|
|
104
|
+
function readJsDoc(sym, checker) {
|
|
105
|
+
const parts = sym.getDocumentationComment(checker);
|
|
106
|
+
if (parts.length === 0)
|
|
107
|
+
return "";
|
|
108
|
+
return parts.map((p) => p.text).join("");
|
|
109
|
+
}
|
|
110
|
+
function readSignature(sym, decl, checker) {
|
|
111
|
+
// For functions, render the call signature.
|
|
112
|
+
const type = checker.getTypeOfSymbolAtLocation(sym, decl);
|
|
113
|
+
const callSigs = type.getCallSignatures();
|
|
114
|
+
if (callSigs.length > 0) {
|
|
115
|
+
return callSigs
|
|
116
|
+
.map((sig) => checker.signatureToString(sig))
|
|
117
|
+
.join(" / ");
|
|
118
|
+
}
|
|
119
|
+
// For non-callable declarations, fall back to the type string.
|
|
120
|
+
if (ts.isVariableDeclaration(decl) ||
|
|
121
|
+
ts.isTypeAliasDeclaration(decl)) {
|
|
122
|
+
return checker.typeToString(type);
|
|
123
|
+
}
|
|
124
|
+
return undefined;
|
|
125
|
+
}
|
|
126
|
+
//# sourceMappingURL=reflect.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reflect.js","sourceRoot":"","sources":["../src/reflect.ts"],"names":[],"mappings":"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"}
|
package/dist/render.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Convert reflection records into Dogsbay ExportPage objects.
|
|
3
|
+
*
|
|
4
|
+
* Each reflection becomes a page with:
|
|
5
|
+
* - h1: the symbol name
|
|
6
|
+
* - kind badge in frontmatter (`type: <kind>`)
|
|
7
|
+
* - signature in a code block (when present)
|
|
8
|
+
* - JSDoc body (when present)
|
|
9
|
+
* - source-file pointer
|
|
10
|
+
*
|
|
11
|
+
* The TreeNode shape is the same the format-astro serializer
|
|
12
|
+
* already understands; no special rendering required on the
|
|
13
|
+
* other side.
|
|
14
|
+
*/
|
|
15
|
+
import type { ExportPage, NavItem } from "@dogsbay/types";
|
|
16
|
+
import type { Reflection } from "./reflect.js";
|
|
17
|
+
export interface RenderInput {
|
|
18
|
+
reflections: Reflection[];
|
|
19
|
+
/** URL prefix segment for emitted pages, e.g. "api". */
|
|
20
|
+
output: string;
|
|
21
|
+
/** Sidebar group label. */
|
|
22
|
+
sidebarLabel: string;
|
|
23
|
+
}
|
|
24
|
+
export interface RenderResult {
|
|
25
|
+
pages: ExportPage[];
|
|
26
|
+
navGroup: NavItem;
|
|
27
|
+
}
|
|
28
|
+
export declare function reflectionsToPages(input: RenderInput): RenderResult;
|
|
29
|
+
//# sourceMappingURL=render.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAanE"}
|
package/dist/render.js
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
export function reflectionsToPages(input) {
|
|
2
|
+
const { reflections, output, sidebarLabel } = input;
|
|
3
|
+
const pages = reflections.map((r) => makePage(r, output));
|
|
4
|
+
const navGroup = {
|
|
5
|
+
label: sidebarLabel,
|
|
6
|
+
children: reflections.map((r) => ({
|
|
7
|
+
label: r.name,
|
|
8
|
+
href: `/${output}/${slugify(r.name)}`,
|
|
9
|
+
})),
|
|
10
|
+
};
|
|
11
|
+
return { pages, navGroup };
|
|
12
|
+
}
|
|
13
|
+
function makePage(r, output) {
|
|
14
|
+
const slug = `${output}/${slugify(r.name)}`;
|
|
15
|
+
const tree = [];
|
|
16
|
+
// Heading
|
|
17
|
+
tree.push({
|
|
18
|
+
type: "heading",
|
|
19
|
+
props: { depth: 1 },
|
|
20
|
+
inline: [{ type: "text", text: r.name }],
|
|
21
|
+
});
|
|
22
|
+
// Kind + source pointer
|
|
23
|
+
tree.push({
|
|
24
|
+
type: "paragraph",
|
|
25
|
+
inline: [
|
|
26
|
+
{ type: "text", text: `Kind: ${r.kind} · Source: ` },
|
|
27
|
+
{ type: "code", text: `${r.sourceFile}:${r.line}` },
|
|
28
|
+
],
|
|
29
|
+
});
|
|
30
|
+
// Signature (when present)
|
|
31
|
+
if (r.signature) {
|
|
32
|
+
tree.push({
|
|
33
|
+
type: "code",
|
|
34
|
+
props: { lang: "typescript", code: r.signature },
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
// JSDoc body
|
|
38
|
+
if (r.doc) {
|
|
39
|
+
for (const para of r.doc.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean)) {
|
|
40
|
+
tree.push({
|
|
41
|
+
type: "paragraph",
|
|
42
|
+
inline: [{ type: "text", text: para }],
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return {
|
|
47
|
+
slug,
|
|
48
|
+
title: r.name,
|
|
49
|
+
tree,
|
|
50
|
+
headings: [{ depth: 1, slug: slugify(r.name), text: r.name }],
|
|
51
|
+
meta: {
|
|
52
|
+
type: kindToMetaType(r.kind),
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
function kindToMetaType(kind) {
|
|
57
|
+
// Map reflection kinds to Dogsbay's `meta.type` taxonomy values.
|
|
58
|
+
// Falls through to "reference" — the closest semantic bucket.
|
|
59
|
+
return "reference";
|
|
60
|
+
}
|
|
61
|
+
function slugify(name) {
|
|
62
|
+
return name
|
|
63
|
+
.replace(/[A-Z]+/g, (m) => m.toLowerCase())
|
|
64
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
65
|
+
.replace(/^-+|-+$/g, "");
|
|
66
|
+
}
|
|
67
|
+
//# sourceMappingURL=render.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}
|
package/dist/schema.d.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Options for `@dogsbay/plugin-typedoc`.
|
|
3
|
+
*
|
|
4
|
+
* The plugin scans a TypeScript project, collects every exported
|
|
5
|
+
* declaration, and produces one Dogsbay page per declaration.
|
|
6
|
+
*/
|
|
7
|
+
export interface TypedocOptions {
|
|
8
|
+
/**
|
|
9
|
+
* Glob or absolute path to the project's tsconfig.json (used to
|
|
10
|
+
* resolve compiler options + include patterns). Resolved relative
|
|
11
|
+
* to the site root. Defaults to `./tsconfig.json`.
|
|
12
|
+
*/
|
|
13
|
+
tsconfig?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Path under which generated API pages live, relative to the
|
|
16
|
+
* site's content root. Default `"api"` → pages emit at slugs
|
|
17
|
+
* like `api/<symbol-name>`.
|
|
18
|
+
*/
|
|
19
|
+
output?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Sidebar group label for the generated nav entries. Default
|
|
22
|
+
* `"API Reference"`.
|
|
23
|
+
*/
|
|
24
|
+
sidebarLabel?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Entry-file globs to include. Each matched file's exported
|
|
27
|
+
* symbols become pages. Resolved against the project's tsconfig
|
|
28
|
+
* `rootDir` (or, failing that, the tsconfig's directory).
|
|
29
|
+
* Default: every `.ts` file in the rootDir.
|
|
30
|
+
*/
|
|
31
|
+
entryPoints?: string[];
|
|
32
|
+
}
|
|
33
|
+
export interface ResolvedTypedocOptions {
|
|
34
|
+
tsconfig: string;
|
|
35
|
+
output: string;
|
|
36
|
+
sidebarLabel: string;
|
|
37
|
+
entryPoints: string[] | undefined;
|
|
38
|
+
}
|
|
39
|
+
export declare function parseOptions(input: unknown): ResolvedTypedocOptions;
|
|
40
|
+
//# sourceMappingURL=schema.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACnC;AAQD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CA8CnE"}
|
package/dist/schema.js
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Options for `@dogsbay/plugin-typedoc`.
|
|
3
|
+
*
|
|
4
|
+
* The plugin scans a TypeScript project, collects every exported
|
|
5
|
+
* declaration, and produces one Dogsbay page per declaration.
|
|
6
|
+
*/
|
|
7
|
+
const DEFAULTS = {
|
|
8
|
+
tsconfig: "./tsconfig.json",
|
|
9
|
+
output: "api",
|
|
10
|
+
sidebarLabel: "API Reference",
|
|
11
|
+
};
|
|
12
|
+
export function parseOptions(input) {
|
|
13
|
+
if (input === undefined || input === null) {
|
|
14
|
+
return { ...DEFAULTS, entryPoints: undefined };
|
|
15
|
+
}
|
|
16
|
+
if (typeof input !== "object" || Array.isArray(input)) {
|
|
17
|
+
throw new Error(`@dogsbay/plugin-typedoc: options must be an object, got ${describe(input)}.`);
|
|
18
|
+
}
|
|
19
|
+
const opts = input;
|
|
20
|
+
const out = { ...DEFAULTS, entryPoints: undefined };
|
|
21
|
+
if (opts.tsconfig !== undefined) {
|
|
22
|
+
if (typeof opts.tsconfig !== "string" || opts.tsconfig.trim() === "") {
|
|
23
|
+
throw new Error(`@dogsbay/plugin-typedoc: options.tsconfig must be a non-empty string.`);
|
|
24
|
+
}
|
|
25
|
+
out.tsconfig = opts.tsconfig;
|
|
26
|
+
}
|
|
27
|
+
if (opts.output !== undefined) {
|
|
28
|
+
if (typeof opts.output !== "string" || opts.output.trim() === "") {
|
|
29
|
+
throw new Error(`@dogsbay/plugin-typedoc: options.output must be a non-empty string.`);
|
|
30
|
+
}
|
|
31
|
+
out.output = opts.output.replace(/^\/+/, "").replace(/\/+$/, "");
|
|
32
|
+
}
|
|
33
|
+
if (opts.sidebarLabel !== undefined) {
|
|
34
|
+
if (typeof opts.sidebarLabel !== "string" || opts.sidebarLabel.trim() === "") {
|
|
35
|
+
throw new Error(`@dogsbay/plugin-typedoc: options.sidebarLabel must be a non-empty string.`);
|
|
36
|
+
}
|
|
37
|
+
out.sidebarLabel = opts.sidebarLabel;
|
|
38
|
+
}
|
|
39
|
+
if (opts.entryPoints !== undefined) {
|
|
40
|
+
if (!Array.isArray(opts.entryPoints) || opts.entryPoints.some((p) => typeof p !== "string")) {
|
|
41
|
+
throw new Error(`@dogsbay/plugin-typedoc: options.entryPoints must be an array of strings.`);
|
|
42
|
+
}
|
|
43
|
+
out.entryPoints = opts.entryPoints;
|
|
44
|
+
}
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
function describe(value) {
|
|
48
|
+
if (value === null)
|
|
49
|
+
return "null";
|
|
50
|
+
if (Array.isArray(value))
|
|
51
|
+
return "array";
|
|
52
|
+
return typeof value;
|
|
53
|
+
}
|
|
54
|
+
//# sourceMappingURL=schema.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoCH,MAAM,QAAQ,GAAgD;IAC5D,QAAQ,EAAE,iBAAiB;IAC3B,MAAM,EAAE,KAAK;IACb,YAAY,EAAE,eAAe;CAC9B,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,EAAE,GAAG,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;IACjD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,2DAA2D,QAAQ,CAAC,KAAK,CAAC,GAAG,CAC9E,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,MAAM,GAAG,GAA2B,EAAE,GAAG,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;IAE5E,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACjE,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC5F,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,WAAuB,CAAC;IACjD,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,OAAO,OAAO,KAAK,CAAC;AACtB,CAAC"}
|
package/package.json
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@dogsbay/plugin-typedoc",
|
|
3
|
+
"version": "0.2.0-beta.81",
|
|
4
|
+
"description": "Generate API-reference pages from a TypeScript project for Dogsbay docs sites.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md"
|
|
17
|
+
],
|
|
18
|
+
"dependencies": {
|
|
19
|
+
"@dogsbay/types": "0.2.0-beta.81"
|
|
20
|
+
},
|
|
21
|
+
"peerDependencies": {
|
|
22
|
+
"typescript": "^5.0.0"
|
|
23
|
+
},
|
|
24
|
+
"devDependencies": {
|
|
25
|
+
"typescript": "^5.7.0",
|
|
26
|
+
"vitest": "^3.0.0",
|
|
27
|
+
"@types/node": "^22.0.0"
|
|
28
|
+
},
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"keywords": [
|
|
31
|
+
"dogsbay",
|
|
32
|
+
"dogsbay-plugin",
|
|
33
|
+
"documentation",
|
|
34
|
+
"typescript",
|
|
35
|
+
"api-reference"
|
|
36
|
+
],
|
|
37
|
+
"repository": {
|
|
38
|
+
"type": "git",
|
|
39
|
+
"url": "https://github.com/dogsbay/dogsbay.git",
|
|
40
|
+
"directory": "packages/plugin-typedoc"
|
|
41
|
+
},
|
|
42
|
+
"scripts": {
|
|
43
|
+
"build": "tsc",
|
|
44
|
+
"test": "vitest run",
|
|
45
|
+
"test:watch": "vitest"
|
|
46
|
+
}
|
|
47
|
+
}
|