chore: add doc generation for AI

docs/modules/Config.ts.md

@@ -49,6 +49,7 @@ export interface Config {
   readonly outDir: string
   readonly theme: string
   readonly enableSearch: boolean
+  readonly enableAI: boolean
   readonly enforceDescriptions: boolean
   readonly enforceExamples: boolean
   readonly enforceVersion: boolean

docs/modules/Domain.ts.md

@@ -12,6 +12,8 @@ Added in v1.0.0
 
 <h2 class="text-delta">Table of contents</h2>
 
+- [accessors](#accessors)
+  - [getPrintables](#getprintables)
 - [constructors](#constructors)
   - [createClass](#createclass)
   - [createConstant](#createconstant)
@@ -35,11 +37,24 @@ Added in v1.0.0
   - [Interface (interface)](#interface-interface)
   - [Method (interface)](#method-interface)
   - [Module (interface)](#module-interface)
+  - [Printable (type alias)](#printable-type-alias)
   - [Property (interface)](#property-interface)
   - [TypeAlias (interface)](#typealias-interface)
 
 ---
 
+# accessors
+
+## getPrintables
+
+**Signature**
+
+```ts
+export declare const getPrintables: (module: Module) => ReadonlyArray<Printable>
+```
+
+Added in v1.0.0
+
 # constructors
 
 ## createClass
@@ -303,6 +318,16 @@ export interface Module extends Documentable {
 
 Added in v1.0.0
 
+## Printable (type alias)
+
+**Signature**
+
+```ts
+export type Printable = Class | Constant | Export | Function | Interface | TypeAlias
+```
+
+Added in v1.0.0
+
 ## Property (interface)
 
 **Signature**

docs/modules/Markdown.ts.md

@@ -14,6 +14,7 @@ Added in v1.0.0
 
 - [printers](#printers)
   - [printModule](#printmodule)
+  - [printPrintableForAI](#printprintableforai)
 
 ---
 
@@ -28,3 +29,17 @@ export declare const printModule: (module: Domain.Module, order: number) => stri
 ```
 
 Added in v1.0.0
+
+## printPrintableForAI
+
+**Signature**
+
+```ts
+export declare const printPrintableForAI: (
+  projectName: string,
+  module: Domain.Module,
+  printable: Domain.Printable
+) => string
+```
+
+Added in v1.0.0

src/Config.ts

@@ -28,6 +28,7 @@ export interface Config {
   readonly outDir: string
   readonly theme: string
   readonly enableSearch: boolean
+  readonly enableAI: boolean
   readonly enforceDescriptions: boolean
   readonly enforceExamples: boolean
   readonly enforceVersion: boolean
@@ -62,6 +63,7 @@ const ConfigSchema = Schema.struct({
   srcDir: Schema.string,
   outDir: Schema.string,
   theme: Schema.string,
+  enableAI: Schema.boolean,
   enableSearch: Schema.boolean,
   enforceDescriptions: Schema.boolean,
   enforceExamples: Schema.boolean,
@@ -99,6 +101,7 @@ const getDefaultConfig = (projectName: string, projectHomepage: string): Config
   srcDir: "src",
   outDir: "docs",
   theme: "pmarsceill/just-the-docs",
+  enableAI: false,
   enableSearch: true,
   enforceDescriptions: false,
   enforceExamples: false,

src/Core.ts

@@ -14,10 +14,10 @@ import chalk from "chalk"
 import * as NodePath from "path"
 import * as ChildProcess from "./ChildProcess"
 import * as Config from "./Config"
-import type * as Domain from "./Domain"
+import * as Domain from "./Domain"
 import * as FileSystem from "./FileSystem"
 import { SimpleLogger } from "./Logger"
-import { printModule } from "./Markdown"
+import { printModule, printPrintableForAI } from "./Markdown"
 import * as Parser from "./Parser"
 import * as Process from "./Process"
 
@@ -35,10 +35,8 @@ const readFiles = pipe(
       Effect.tap((paths) => Effect.logInfo(chalk.bold(`${paths.length} module(s) found`))),
       Effect.flatMap(
         Effect.forEachPar((path) =>
-          Effect.map(
-            fileSystem.readFile(path),
-            (content) => FileSystem.makeFile(path, content, false)
-          )
+          Effect.map(fileSystem.readFile(path), (content) =>
+            FileSystem.makeFile(path, content, false))
         )
       )
     )
@@ -106,9 +104,7 @@ const getModules = (files: ReadonlyArray<FileSystem.File>) =>
     Parser.parseFiles(files),
     Effect.mapError((errors) =>
       ParseError({
-        message: errors
-          .map((errors) => errors.join("\n"))
-          .join("\n")
+        message: errors.map((errors) => errors.join("\n")).join("\n")
       })
     )
   )
@@ -143,9 +139,7 @@ const getExampleFiles = (modules: ReadonlyArray<Domain.Module>) =>
         const prefix = module.path.join("-")
 
         const getDocumentableExamples = (id: string) =>
-          (
-            documentable: Domain.Documentable
-          ): ReadonlyArray<FileSystem.File> =>
+          (documentable: Domain.Documentable): ReadonlyArray<FileSystem.File> =>
             pipe(
               documentable.examples,
               ReadonlyArray.map((content, i) =>
@@ -273,9 +267,8 @@ const spawnTsNode = pipe(
   )
 )
 
-const writeFiles = (
-  files: ReadonlyArray<FileSystem.File>
-) => Effect.forEachDiscard(files, writeFile)
+const writeFiles = (files: ReadonlyArray<FileSystem.File>) =>
+  Effect.forEachDiscard(files, writeFile)
 
 const writeExamples = (examples: ReadonlyArray<FileSystem.File>) =>
   pipe(
@@ -320,12 +313,9 @@ const getMarkdown = (modules: ReadonlyArray<Domain.Module>) =>
     Effect.bind("home", () => getHome),
     Effect.bind("index", () => getModulesIndex),
     Effect.bind("yml", () => getConfigYML),
-    Effect.flatMap(({ home, index, yml }) =>
-      pipe(
-        getModuleMarkdownFiles(modules),
-        Effect.map((files) => [home, index, yml].concat(files))
-      )
-    )
+    Effect.bind("modules", () => getModuleMarkdownFiles(modules)),
+    Effect.bind("ai", () => maybeGetAIMarkdownFiles(modules)),
+    Effect.map(({ ai, home, index, modules, yml }) => [home, index, yml].concat(modules).concat(ai))
   )
 
 const getHome = pipe(
@@ -441,6 +431,14 @@ const getMarkdownOutputPath = (module: Domain.Module) =>
       `${module.path.slice(1).join(NodePath.sep)}.md`
     ))
 
+const getAIMarkdownOutputPath = (module: Domain.Module, printable: Domain.Printable) =>
+  Effect.map(Config.Config, (config) =>
+    join(
+      config.outDir,
+      "ai",
+      `${module.path.slice(1).join("-").replace(/\.ts$/, "")}-${printable.name}.md`
+    ))
+
 const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
   Effect.forEachWithIndex(modules, (module, order) =>
     pipe(
@@ -450,6 +448,37 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
       Effect.map(({ content, outputPath }) => FileSystem.makeFile(outputPath, content, true))
     ))
 
+const getAIMarkdownFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
+  pipe(
+    modules,
+    ReadonlyArray.flatMap((module) =>
+      pipe(
+        Domain.getPrintables(module),
+        ReadonlyArray.map((printable) => [module, printable] as const)
+      )
+    ),
+    ReadonlyArray.filter(([, printable]) =>
+      printable.description._tag === "Some" &&
+      (printable.examples.length > 0 || printable.description.value.includes("```") ||
+        printable.description.value.length >= 115)
+    ),
+    Effect.forEach(([module, printable]) =>
+      pipe(
+        Effect.Do(),
+        Effect.bind("outputPath", () => getAIMarkdownOutputPath(module, printable)),
+        Effect.let("content", () => printPrintableForAI(projectName, module, printable)),
+        Effect.map(({ content, outputPath }) => FileSystem.makeFile(outputPath, content, true))
+      )
+    )
+  )
+
+const maybeGetAIMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
+  Effect.flatMap(
+    Config.Config,
+    (config) =>
+      config.enableAI ? getAIMarkdownFiles(config.projectName, modules) : Effect.succeed([])
+  )
+
 // -------------------------------------------------------------------------------------
 // writeMarkdown
 // -------------------------------------------------------------------------------------
@@ -487,7 +516,9 @@ export const main: Effect.Effect<never, never, void> = pipe(
   Effect.flatMap(getMarkdown),
   Effect.zipLeft(Effect.logInfo("writing markdown files...")),
   Effect.flatMap(writeMarkdown),
-  Effect.zipLeft(Effect.logInfo(chalk.bold.green("Docs generation succeeded!"))),
+  Effect.zipLeft(
+    Effect.logInfo(chalk.bold.green("Docs generation succeeded!"))
+  ),
   Logger.withMinimumLogLevel(LogLevel.Debug),
   Effect.provideLayer(MainLayer),
   Effect.catchTags({
@@ -508,7 +539,11 @@ export const main: Effect.Effect<never, never, void> = pipe(
       ),
     SpawnError: ({ args, command, error }) =>
       Effect.dieMessage(
-        `Unable to spawn child process for command: '${command} ${args.join(" ")}'\n${error}`
+        `Unable to spawn child process for command: '${command} ${
+          args.join(
+            " "
+          )
+        }'\n${error}`
       ),
     // Parsing errors
     ParseJsonError: ({ content }) => Effect.dieMessage(`Unable to parse JSON: ${content}`),

src/Domain.ts

@@ -3,6 +3,7 @@
  */
 
 import type * as Option from "@effect/data/Option"
+import * as ReadonlyArray from "@effect/data/ReadonlyArray"
 import * as String from "@effect/data/String"
 import * as order from "@effect/data/typeclass/Order"
 
@@ -112,6 +113,18 @@ export interface Export extends Documentable {
  */
 export type Example = string
 
+/**
+ * @category model
+ * @since 1.0.0
+ */
+export type Printable =
+  | Class
+  | Constant
+  | Export
+  | Function
+  | Interface
+  | TypeAlias
+
 // -------------------------------------------------------------------------------------
 // constructors
 // -------------------------------------------------------------------------------------
@@ -268,6 +281,24 @@ export const createExport = (
   signature
 })
 
+// -------------------------------------------------------------------------------------
+// accessors
+// -------------------------------------------------------------------------------------
+
+/**
+ * @category accessors
+ * @since 1.0.0
+ */
+export const getPrintables = (module: Module): ReadonlyArray<Printable> =>
+  ReadonlyArray.getMonoid<Printable>().combineAll([
+    module.classes,
+    module.constants,
+    module.exports,
+    module.functions,
+    module.interfaces,
+    module.typeAliases
+  ])
+
 /**
  * @category instances
  * @since 1.0.0