Skip to content

Commit

Permalink
chore: add doc generation for AI
Browse files Browse the repository at this point in the history
  • Loading branch information
@tim-smart
tim-smart committed Oct 20, 2024
1 parent b77f746 commit 8843141
Show file tree
Hide file tree
Showing 10 changed files with 216 additions and 74 deletions.
47 changes: 16 additions & 31 deletions docs/modules/Configuration.ts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,39 +37,23 @@ Added in v1.0.0

```ts
export declare const ConfigurationSchema: Schema.Struct<{
$schema: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
projectHomepage: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
srcDir: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
outDir: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
theme: Schema.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>
enableSearch: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
enforceDescriptions: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
enforceExamples: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
enforceVersion: Schema.PropertySignature<"?:", boolean | undefined, never, "?:", boolean | undefined, never>
exclude: Schema.PropertySignature<
"?:",
readonly string[] | undefined,
never,
"?:",
readonly string[] | undefined,
never
$schema: Schema.optional<typeof Schema.String>
projectHomepage: Schema.optional<typeof Schema.String>
srcDir: Schema.optional<typeof Schema.String>
outDir: Schema.optional<typeof Schema.String>
theme: Schema.optional<typeof Schema.String>
enableSearch: Schema.optional<typeof Schema.Boolean>
enforceDescriptions: Schema.optional<typeof Schema.Boolean>
enforceExamples: Schema.optional<typeof Schema.Boolean>
enforceVersion: Schema.optional<typeof Schema.Boolean>
exclude: Schema.optional<Schema.Array$<typeof Schema.String>>
parseCompilerOptions: Schema.optional<
Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>
>
parseCompilerOptions: Schema.PropertySignature<
"?:",
string | { readonly [x: string]: unknown } | undefined,
never,
"?:",
string | { readonly [x: string]: unknown } | undefined,
never
>
examplesCompilerOptions: Schema.PropertySignature<
"?:",
string | { readonly [x: string]: unknown } | undefined,
never,
"?:",
string | { readonly [x: string]: unknown } | undefined,
never
examplesCompilerOptions: Schema.optional<
Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>
>
enableAI: Schema.optional<typeof Schema.Boolean>
}>
```

Expand All @@ -94,6 +78,7 @@ export interface ConfigurationShape {
readonly exclude: ReadonlyArray<string>
readonly parseCompilerOptions: Record<string, unknown>
readonly examplesCompilerOptions: Record<string, unknown>
readonly enableAI: boolean
}
```

Expand Down
25 changes: 25 additions & 0 deletions docs/modules/Domain.ts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Added in v1.0.0

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

- [accessors](#accessors)
- [printablesFromModule](#printablesfrommodule)
- [constructors](#constructors)
- [createClass](#createclass)
- [createConstant](#createconstant)
Expand All @@ -37,13 +39,26 @@ Added in v1.0.0
- [Module (interface)](#module-interface)
- [NamedDoc (interface)](#nameddoc-interface)
- [Namespace (interface)](#namespace-interface)
- [Printable (type alias)](#printable-type-alias)
- [Property (interface)](#property-interface)
- [TypeAlias (interface)](#typealias-interface)
- [sorting](#sorting)
- [ByPath](#bypath)

---

# accessors

## printablesFromModule

**Signature**

```ts
export declare const printablesFromModule: (module: Module) => ReadonlyArray<Printable>
```
Added in v1.0.0
# constructors
## createClass
Expand Down Expand Up @@ -364,6 +379,16 @@ export interface Namespace extends NamedDoc {

Added in v1.0.0

## Printable (type alias)

**Signature**

```ts
export type Printable = Class | Constant | Export | Function | Interface | TypeAlias | Namespace
```
Added in v1.0.0
## Property (interface)
**Signature**
Expand Down
15 changes: 15 additions & 0 deletions docs/modules/Markdown.ts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Added in v1.0.0

- [printers](#printers)
- [printModule](#printmodule)
- [printPrintableForAI](#printprintableforai)

---

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

Added in v1.0.0

## printPrintableForAI

**Signature**

```ts
export declare const printPrintableForAI: (
projectName: string,
module: Domain.Module,
printable: Domain.Printable
) => Effect.Effect<string, never, never>
```
Added in v1.0.0
47 changes: 20 additions & 27 deletions schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,81 +7,69 @@
"required": [],
"properties": {
"$schema": {
"type": "string",
"description": "a string",
"title": "string"
"type": "string"
},
"projectHomepage": {
"type": "string",
"description": "Will link to the project homepage from the Auxiliary Links of the generated documentation.",
"title": "string"
"description": "Will link to the project homepage from the Auxiliary Links of the generated documentation."
},
"srcDir": {
"type": "string",
"description": "The directory in which docgen will search for TypeScript files to parse.",
"title": "string",
"default": "src"
},
"outDir": {
"type": "string",
"description": "The directory to which docgen will generate its output markdown documents.",
"title": "string",
"default": "docs"
},
"theme": {
"type": "string",
"description": "The theme that docgen will specify should be used for GitHub Docs in the generated _config.yml file.",
"title": "string",
"default": "mikearnaldi/just-the-docs"
},
"enableSearch": {
"type": "boolean",
"description": "Whether or not search should be enabled for GitHub Docs in the generated _config.yml file.",
"title": "boolean",
"default": true
},
"enforceDescriptions": {
"type": "boolean",
"description": "Whether or not descriptions for each module export should be required.",
"title": "boolean",
"default": false
},
"enforceExamples": {
"type": "boolean",
"description": "Whether or not @example tags for each module export should be required. (Note: examples will not be enforced in module documentation)",
"title": "boolean",
"default": false
},
"enforceVersion": {
"type": "boolean",
"description": "Whether or not @since tags for each module export should be required.",
"title": "boolean",
"default": true
},
"exclude": {
"type": "array",
"items": {
"type": "string",
"description": "a string",
"title": "string"
"type": "string"
},
"description": "An array of glob strings specifying files that should be excluded from the documentation.",
"default": []
},
"parseCompilerOptions": {
"anyOf": [
{
"type": "string",
"description": "a string",
"title": "string"
"type": "string"
},
{
"type": "object",
"required": [],
"properties": {},
"additionalProperties": {
"$id": "/schemas/unknown",
"title": "unknown"
"patternProperties": {
"": {
"$id": "/schemas/unknown",
"title": "unknown"
}
}
}
],
Expand All @@ -91,22 +79,27 @@
"examplesCompilerOptions": {
"anyOf": [
{
"type": "string",
"description": "a string",
"title": "string"
"type": "string"
},
{
"type": "object",
"required": [],
"properties": {},
"additionalProperties": {
"$id": "/schemas/unknown",
"title": "unknown"
"patternProperties": {
"": {
"$id": "/schemas/unknown",
"title": "unknown"
}
}
}
],
"description": "tsconfig for the examples options (or path to a tsconfig)",
"default": {}
},
"enableAI": {
"type": "boolean",
"description": "Whether or not to enable AI for the examples",
"default": true
}
},
"additionalProperties": false
Expand Down
14 changes: 13 additions & 1 deletion src/CLI.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,17 @@ const examplesCompilerOptions = Options.file("examples-tsconfig-file", { exists:
Options.optional
)

const enableAI = Options.boolean("no-run-examples", {
ifPresent: false,
negationNames: ["run-examples"]
}).pipe(
Options.withFallbackConfig(Config.boolean("enableAI")),
Options.withDefault(true),
Options.withDescription(
"Whether or not to generate AI documentation for the project"
)
)

const options = {
projectHomepage,
srcDir,
Expand All @@ -168,7 +179,8 @@ const options = {
runExamples,
exclude,
parseCompilerOptions,
examplesCompilerOptions
examplesCompilerOptions,
enableAI
}

/** @internal */
Expand Down
6 changes: 6 additions & 0 deletions src/Configuration.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@ export const ConfigurationSchema = Schema.Struct({
examplesCompilerOptions: Schema.optional(compilerOptionsSchema).annotations({
description: "tsconfig for the examples options (or path to a tsconfig)",
default: {}
}),
enableAI: Schema.optional(Schema.Boolean).annotations({
description: "Whether or not to enable AI for the examples",
default: true
})
}).annotations({ identifier: "ConfigurationSchema" })

Expand All @@ -100,6 +104,7 @@ export interface ConfigurationShape {
readonly exclude: ReadonlyArray<string>
readonly parseCompilerOptions: Record<string, unknown>
readonly examplesCompilerOptions: Record<string, unknown>
readonly enableAI: boolean
}

/**
Expand Down Expand Up @@ -244,6 +249,7 @@ export const load = (args: {
readonly exclude: ReadonlyArray<string>
readonly parseCompilerOptions: Option.Option<string | Record<string, unknown>>
readonly examplesCompilerOptions: Option.Option<string | Record<string, unknown>>
readonly enableAI: boolean
}) =>
Effect.gen(function*(_) {
// Extract the requisite services
Expand Down
44 changes: 41 additions & 3 deletions src/Core.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,15 @@ import chalk from "chalk"
import * as Array from "effect/Array"
import * as Chunk from "effect/Chunk"
import * as Effect from "effect/Effect"
import { pipe } from "effect/Function"
import * as Stream from "effect/Stream"
import * as String from "effect/String"
import * as Glob from "glob"
import * as Configuration from "./Configuration.js"
import type * as Domain from "./Domain.js"
import * as Domain from "./Domain.js"
import { DocgenError } from "./Error.js"
import * as File from "./File.js"
import { printModule } from "./Markdown.js"
import { printModule, printPrintableForAI } from "./Markdown.js"
import * as Parser from "./Parser.js"
import * as Process from "./Process.js"

Expand Down Expand Up @@ -380,7 +381,8 @@ const getMarkdown = (modules: ReadonlyArray<Domain.Module>) =>
const index = yield* _(getMarkdownIndex)
const yml = yield* _(getMarkdownConfigYML)
const moduleFiles = yield* _(getModuleMarkdownFiles(modules))
return [homepage, index, yml, ...moduleFiles]
const aiFiles = yield* _(maybeGetAIMarkdownFiles(modules))
return [homepage, index, yml, ...moduleFiles, ...aiFiles]
})

const getMarkdownHomepage = Effect.gen(function*(_) {
Expand Down Expand Up @@ -482,6 +484,14 @@ const getModuleMarkdownOutputPath = (module: Domain.Module) =>
))
)

const getAIMarkdownOutputPath = (module: Domain.Module, printable: Domain.Printable) =>
Effect.map(Effect.all([Configuration.Configuration, Path.Path]), ([config, path]) =>
path.join(
config.outDir,
"ai",
`${module.path.slice(1).join("-").replace(/\.ts$/, "")}-${printable.name}.md`
))

const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
Effect.forEach(modules, (module, order) =>
Effect.gen(function*(_) {
Expand All @@ -490,6 +500,34 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
return File.createFile(outputPath, content, true)
}))

const getAIMarkdownFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
Effect.gen(function*(_) {
const aiModules = pipe(
modules,
Array.flatMap((module) =>
pipe(
Domain.printablesFromModule(module),
Array.map((printable) => ({ module, printable }))
)
),
Array.filter(({ printable }) => printable.description._tag === "Some")
)

return yield* _(Effect.forEach(aiModules, ({ module, printable }) =>
Effect.gen(function*(_) {
const outputPath = yield* _(getAIMarkdownOutputPath(module, printable))
const content = yield* _(printPrintableForAI(projectName, module, printable))
return File.createFile(outputPath, content, true)
})))
})

const maybeGetAIMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
Effect.flatMap(
Configuration.Configuration,
(config) =>
config.enableAI ? getAIMarkdownFiles(config.projectName, modules) : Effect.succeed([])
)

const writeMarkdown = (files: ReadonlyArray<File.File>) =>
Effect.gen(function*(_) {
const config = yield* _(Configuration.Configuration)
Expand Down
Loading

0 comments on commit 8843141

Please sign in to comment.