Skip to content

Commit 8843141

Browse files
tim-smarttim-smart
committed
chore: add doc generation for AI
1 parent b77f746 commit 8843141

File tree

10 files changed

+216
-74
lines changed

10 files changed

+216
-74
lines changed

‎docs/modules/Configuration.ts.md‎

Lines changed: 16 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -37,39 +37,23 @@ Added in v1.0.0
3737

3838
```ts
3939
export declare const ConfigurationSchema: Schema.Struct<{
40-
$schema: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
41-
projectHomepage: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
42-
srcDir: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
43-
outDir: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
44-
theme: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
45-
enableSearch: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
46-
enforceDescriptions: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
47-
enforceExamples: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
48-
enforceVersion: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
49-
exclude: Schema.PropertySignature<
50-
"?:",
51-
readonly string[] | undefined,
52-
never,
53-
"?:",
54-
readonly string[] | undefined,
55-
never
40+
$schema: Schema.optional<typeof Schema.String>
41+
projectHomepage: Schema.optional<typeof Schema.String>
42+
srcDir: Schema.optional<typeof Schema.String>
43+
outDir: Schema.optional<typeof Schema.String>
44+
theme: Schema.optional<typeof Schema.String>
45+
enableSearch: Schema.optional<typeof Schema.Boolean>
46+
enforceDescriptions: Schema.optional<typeof Schema.Boolean>
47+
enforceExamples: Schema.optional<typeof Schema.Boolean>
48+
enforceVersion: Schema.optional<typeof Schema.Boolean>
49+
exclude: Schema.optional<Schema.Array$<typeof Schema.String>>
50+
parseCompilerOptions: Schema.optional<
51+
Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>
5652
>
57-
parseCompilerOptions: Schema.PropertySignature<
58-
"?:",
59-
string | { readonly [x: string]: unknown } | undefined,
60-
never,
61-
"?:",
62-
string | { readonly [x: string]: unknown } | undefined,
63-
never
64-
>
65-
examplesCompilerOptions: Schema.PropertySignature<
66-
"?:",
67-
string | { readonly [x: string]: unknown } | undefined,
68-
never,
69-
"?:",
70-
string | { readonly [x: string]: unknown } | undefined,
71-
never
53+
examplesCompilerOptions: Schema.optional<
54+
Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>
7255
>
56+
enableAI: Schema.optional<typeof Schema.Boolean>
7357
}>
7458
```
7559

@@ -94,6 +78,7 @@ export interface ConfigurationShape {
9478
readonly exclude: ReadonlyArray<string>
9579
readonly parseCompilerOptions: Record<string, unknown>
9680
readonly examplesCompilerOptions: Record<string, unknown>
81+
readonly enableAI: boolean
9782
}
9883
```
9984

‎docs/modules/Domain.ts.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Added in v1.0.0
1212

1313
<h2 class="text-delta">Table of contents</h2>
1414

15+
- [accessors](#accessors)
16+
- [printablesFromModule](#printablesfrommodule)
1517
- [constructors](#constructors)
1618
- [createClass](#createclass)
1719
- [createConstant](#createconstant)
@@ -37,13 +39,26 @@ Added in v1.0.0
3739
- [Module (interface)](#module-interface)
3840
- [NamedDoc (interface)](#nameddoc-interface)
3941
- [Namespace (interface)](#namespace-interface)
42+
- [Printable (type alias)](#printable-type-alias)
4043
- [Property (interface)](#property-interface)
4144
- [TypeAlias (interface)](#typealias-interface)
4245
- [sorting](#sorting)
4346
- [ByPath](#bypath)
4447

4548
---
4649

50+
# accessors
51+
52+
## printablesFromModule
53+
54+
**Signature**
55+
56+
```ts
57+
export declare const printablesFromModule: (module: Module) => ReadonlyArray<Printable>
58+
```
59+
60+
Added in v1.0.0
61+
4762
# constructors
4863
4964
## createClass
@@ -364,6 +379,16 @@ export interface Namespace extends NamedDoc {
364379

365380
Added in v1.0.0
366381

382+
## Printable (type alias)
383+
384+
**Signature**
385+
386+
```ts
387+
export type Printable = Class | Constant | Export | Function | Interface | TypeAlias | Namespace
388+
```
389+
390+
Added in v1.0.0
391+
367392
## Property (interface)
368393
369394
**Signature**

‎docs/modules/Markdown.ts.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Added in v1.0.0
1414

1515
- [printers](#printers)
1616
- [printModule](#printmodule)
17+
- [printPrintableForAI](#printprintableforai)
1718

1819
---
1920

@@ -40,3 +41,17 @@ console.log(Markdown.printModule(m, 0))
4041
```
4142

4243
Added in v1.0.0
44+
45+
## printPrintableForAI
46+
47+
**Signature**
48+
49+
```ts
50+
export declare const printPrintableForAI: (
51+
projectName: string,
52+
module: Domain.Module,
53+
printable: Domain.Printable
54+
) => Effect.Effect<string, never, never>
55+
```
56+
57+
Added in v1.0.0

‎schema.json‎

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -7,81 +7,69 @@
77
"required": [],
88
"properties": {
99
"$schema": {
10-
"type": "string",
11-
"description": "a string",
12-
"title": "string"
10+
"type": "string"
1311
},
1412
"projectHomepage": {
1513
"type": "string",
16-
"description": "Will link to the project homepage from the Auxiliary Links of the generated documentation.",
17-
"title": "string"
14+
"description": "Will link to the project homepage from the Auxiliary Links of the generated documentation."
1815
},
1916
"srcDir": {
2017
"type": "string",
2118
"description": "The directory in which docgen will search for TypeScript files to parse.",
22-
"title": "string",
2319
"default": "src"
2420
},
2521
"outDir": {
2622
"type": "string",
2723
"description": "The directory to which docgen will generate its output markdown documents.",
28-
"title": "string",
2924
"default": "docs"
3025
},
3126
"theme": {
3227
"type": "string",
3328
"description": "The theme that docgen will specify should be used for GitHub Docs in the generated _config.yml file.",
34-
"title": "string",
3529
"default": "mikearnaldi/just-the-docs"
3630
},
3731
"enableSearch": {
3832
"type": "boolean",
3933
"description": "Whether or not search should be enabled for GitHub Docs in the generated _config.yml file.",
40-
"title": "boolean",
4134
"default": true
4235
},
4336
"enforceDescriptions": {
4437
"type": "boolean",
4538
"description": "Whether or not descriptions for each module export should be required.",
46-
"title": "boolean",
4739
"default": false
4840
},
4941
"enforceExamples": {
5042
"type": "boolean",
5143
"description": "Whether or not @example tags for each module export should be required. (Note: examples will not be enforced in module documentation)",
52-
"title": "boolean",
5344
"default": false
5445
},
5546
"enforceVersion": {
5647
"type": "boolean",
5748
"description": "Whether or not @since tags for each module export should be required.",
58-
"title": "boolean",
5949
"default": true
6050
},
6151
"exclude": {
6252
"type": "array",
6353
"items": {
64-
"type": "string",
65-
"description": "a string",
66-
"title": "string"
54+
"type": "string"
6755
},
6856
"description": "An array of glob strings specifying files that should be excluded from the documentation.",
6957
"default": []
7058
},
7159
"parseCompilerOptions": {
7260
"anyOf": [
7361
{
74-
"type": "string",
75-
"description": "a string",
76-
"title": "string"
62+
"type": "string"
7763
},
7864
{
7965
"type": "object",
8066
"required": [],
8167
"properties": {},
82-
"additionalProperties": {
83-
"$id": "/schemas/unknown",
84-
"title": "unknown"
68+
"patternProperties": {
69+
"": {
70+
"$id": "/schemas/unknown",
71+
"title": "unknown"
72+
}
8573
}
8674
}
8775
],
@@ -91,22 +79,27 @@
9179
"examplesCompilerOptions": {
9280
"anyOf": [
9381
{
94-
"type": "string",
95-
"description": "a string",
96-
"title": "string"
82+
"type": "string"
9783
},
9884
{
9985
"type": "object",
10086
"required": [],
10187
"properties": {},
102-
"additionalProperties": {
103-
"$id": "/schemas/unknown",
104-
"title": "unknown"
88+
"patternProperties": {
89+
"": {
90+
"$id": "/schemas/unknown",
91+
"title": "unknown"
92+
}
10593
}
10694
}
10795
],
10896
"description": "tsconfig for the examples options (or path to a tsconfig)",
10997
"default": {}
98+
},
99+
"enableAI": {
100+
"type": "boolean",
101+
"description": "Whether or not to enable AI for the examples",
102+
"default": true
110103
}
111104
},
112105
"additionalProperties": false

‎src/CLI.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,17 @@ const examplesCompilerOptions = Options.file("examples-tsconfig-file", { exists:
156156
Options.optional
157157
)
158158

159+
const enableAI = Options.boolean("no-run-examples", {
160+
ifPresent: false,
161+
negationNames: ["run-examples"]
162+
}).pipe(
163+
Options.withFallbackConfig(Config.boolean("enableAI")),
164+
Options.withDefault(true),
165+
Options.withDescription(
166+
"Whether or not to generate AI documentation for the project"
167+
)
168+
)
169+
159170
const options = {
160171
projectHomepage,
161172
srcDir,
@@ -168,7 +179,8 @@ const options = {
168179
runExamples,
169180
exclude,
170181
parseCompilerOptions,
171-
examplesCompilerOptions
182+
examplesCompilerOptions,
183+
enableAI
172184
}
173185

174186
/** @internal */

‎src/Configuration.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ export const ConfigurationSchema = Schema.Struct({
7979
examplesCompilerOptions: Schema.optional(compilerOptionsSchema).annotations({
8080
description: "tsconfig for the examples options (or path to a tsconfig)",
8181
default: {}
82+
}),
83+
enableAI: Schema.optional(Schema.Boolean).annotations({
84+
description: "Whether or not to enable AI for the examples",
85+
default: true
8286
})
8387
}).annotations({ identifier: "ConfigurationSchema" })
8488

@@ -100,6 +104,7 @@ export interface ConfigurationShape {
100104
readonly exclude: ReadonlyArray<string>
101105
readonly parseCompilerOptions: Record<string, unknown>
102106
readonly examplesCompilerOptions: Record<string, unknown>
107+
readonly enableAI: boolean
103108
}
104109

105110
/**
@@ -244,6 +249,7 @@ export const load = (args: {
244249
readonly exclude: ReadonlyArray<string>
245250
readonly parseCompilerOptions: Option.Option<string | Record<string, unknown>>
246251
readonly examplesCompilerOptions: Option.Option<string | Record<string, unknown>>
252+
readonly enableAI: boolean
247253
}) =>
248254
Effect.gen(function*(_) {
249255
// Extract the requisite services

‎src/Core.ts‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,15 @@ import chalk from "chalk"
1111
import * as Array from "effect/Array"
1212
import * as Chunk from "effect/Chunk"
1313
import * as Effect from "effect/Effect"
14+
import { pipe } from "effect/Function"
1415
import * as Stream from "effect/Stream"
1516
import * as String from "effect/String"
1617
import * as Glob from "glob"
1718
import * as Configuration from "./Configuration.js"
18-
import type * as Domain from "./Domain.js"
19+
import * as Domain from "./Domain.js"
1920
import { DocgenError } from "./Error.js"
2021
import * as File from "./File.js"
21-
import { printModule } from "./Markdown.js"
22+
import { printModule, printPrintableForAI } from "./Markdown.js"
2223
import * as Parser from "./Parser.js"
2324
import * as Process from "./Process.js"
2425

@@ -380,7 +381,8 @@ const getMarkdown = (modules: ReadonlyArray<Domain.Module>) =>
380381
const index = yield* _(getMarkdownIndex)
381382
const yml = yield* _(getMarkdownConfigYML)
382383
const moduleFiles = yield* _(getModuleMarkdownFiles(modules))
383-
return [homepage, index, yml, ...moduleFiles]
384+
const aiFiles = yield* _(maybeGetAIMarkdownFiles(modules))
385+
return [homepage, index, yml, ...moduleFiles, ...aiFiles]
384386
})
385387

386388
const getMarkdownHomepage = Effect.gen(function*(_) {
@@ -482,6 +484,14 @@ const getModuleMarkdownOutputPath = (module: Domain.Module) =>
482484
))
483485
)
484486

487+
const getAIMarkdownOutputPath = (module: Domain.Module, printable: Domain.Printable) =>
488+
Effect.map(Effect.all([Configuration.Configuration, Path.Path]), ([config, path]) =>
489+
path.join(
490+
config.outDir,
491+
"ai",
492+
`${module.path.slice(1).join("-").replace(/\.ts$/, "")}-${printable.name}.md`
493+
))
494+
485495
const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
486496
Effect.forEach(modules, (module, order) =>
487497
Effect.gen(function*(_) {
@@ -490,6 +500,34 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
490500
return File.createFile(outputPath, content, true)
491501
}))
492502

503+
const getAIMarkdownFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
504+
Effect.gen(function*(_) {
505+
const aiModules = pipe(
506+
modules,
507+
Array.flatMap((module) =>
508+
pipe(
509+
Domain.printablesFromModule(module),
510+
Array.map((printable) => ({ module, printable }))
511+
)
512+
),
513+
Array.filter(({ printable }) => printable.description._tag === "Some")
514+
)
515+
516+
return yield* _(Effect.forEach(aiModules, ({ module, printable }) =>
517+
Effect.gen(function*(_) {
518+
const outputPath = yield* _(getAIMarkdownOutputPath(module, printable))
519+
const content = yield* _(printPrintableForAI(projectName, module, printable))
520+
return File.createFile(outputPath, content, true)
521+
})))
522+
})
523+
524+
const maybeGetAIMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
525+
Effect.flatMap(
526+
Configuration.Configuration,
527+
(config) =>
528+
config.enableAI ? getAIMarkdownFiles(config.projectName, modules) : Effect.succeed([])
529+
)
530+
493531
const writeMarkdown = (files: ReadonlyArray<File.File>) =>
494532
Effect.gen(function*(_) {
495533
const config = yield* _(Configuration.Configuration)

0 commit comments

Comments
 (0)