chore: add doc generation for AI

Author: tim-smart

docs/modules/Config.ts.md

@@ -57,6 +57,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)
+  - [printablesFromModule](#printablesfrommodule)
 - [constructors](#constructors)
   - [createClass](#createclass)
   - [createConstant](#createconstant)
@@ -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
@@ -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**

docs/modules/Markdown.ts.md

@@ -14,6 +14,7 @@ Added in v1.0.0
 
 - [printers](#printers)
   - [printModule](#printmodule)
+  - [printPrintableForAI](#printprintableforai)
 
 ---
 
@@ -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<never, never, string>
+```
+
+Added in v1.0.0

src/Config.ts

@@ -76,6 +76,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
@@ -128,6 +129,7 @@ export const getDefaultConfig = (name: string, homepage: string): Config => ({
   srcDir: "src",
   outDir: "docs",
   theme: "mikearnaldi/just-the-docs",
+  enableAI: true,
   enableSearch: true,
   enforceDescriptions: false,
   enforceExamples: false,

src/Core.ts

@@ -4,13 +4,13 @@
 
 import { Path } from "@effect/platform-node"
 import chalk from "chalk"
-import { Console, Effect, Layer, Logger, LogLevel, ReadonlyArray, String } from "effect"
+import { Console, Effect, Layer, Logger, LogLevel, pipe, ReadonlyArray, String } from "effect"
 import * as ChildProcess from "./CommandExecutor.js"
 import * as Config from "./Config.js"
-import type * as Domain from "./Domain.js"
+import * as Domain from "./Domain.js"
 import * as FileSystem from "./FileSystem.js"
 import { SimpleLogger } from "./Logger.js"
-import { printModule } from "./Markdown.js"
+import { printModule, printPrintableForAI } from "./Markdown.js"
 import * as Parser from "./Parser.js"
 import * as Process from "./Process.js"
 
@@ -289,7 +289,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*(_) {
@@ -388,6 +389,14 @@ const getModuleMarkdownOutputPath = (module: Domain.Module) =>
       `${module.path.slice(1).join(path.sep)}.md`
     )))
 
+const getAIMarkdownOutputPath = (module: Domain.Module, printable: Domain.Printable) =>
+  Effect.map(Effect.all([Config.Config, 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*(_) {
@@ -396,6 +405,34 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
       return FileSystem.createFile(outputPath, content, true)
     }))
 
+const getAIMarkdownFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
+  Effect.gen(function*(_) {
+    const aiModules = pipe(
+      modules,
+      ReadonlyArray.flatMap((module) =>
+        pipe(
+          Domain.printablesFromModule(module),
+          ReadonlyArray.map((printable) => ({ module, printable }))
+        )
+      ),
+      ReadonlyArray.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 FileSystem.createFile(outputPath, content, true)
+      })))
+  })
+
+const maybeGetAIMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
+  Effect.flatMap(
+    Config.Config,
+    (config) =>
+      config.enableAI ? getAIMarkdownFiles(config.projectName, modules) : Effect.succeed([])
+  )
+
 const writeMarkdown = (files: ReadonlyArray<FileSystem.File>) =>
   Effect.gen(function*(_) {
     const config = yield* _(Config.Config)

src/Domain.ts

@@ -138,6 +138,19 @@ export interface Namespace extends NamedDoc {
   readonly namespaces: ReadonlyArray<Namespace>
 }
 
+/**
+ * @category model
+ * @since 1.0.0
+ */
+export type Printable =
+  | Class
+  | Constant
+  | Export
+  | Function
+  | Interface
+  | TypeAlias
+  | Namespace
+
 // -------------------------------------------------------------------------------------
 // constructors
 // -------------------------------------------------------------------------------------
@@ -273,6 +286,24 @@ export const createExport = (doc: NamedDoc, signature: string): Export => ({
   signature
 })
 
+// -------------------------------------------------------------------------------------
+// accessors
+// -------------------------------------------------------------------------------------
+
+/**
+ * @category accessors
+ * @since 1.0.0
+ */
+export const printablesFromModule = (module: Module): ReadonlyArray<Printable> =>
+  [
+    module.classes,
+    module.constants,
+    module.exports,
+    module.functions,
+    module.interfaces,
+    module.typeAliases
+  ].flat()
+
 /**
  * @category constructors
  * @since 1.0.0

src/Markdown.ts

@@ -6,15 +6,6 @@ import { pipe } from "effect/Function"
 import * as Prettier from "prettier"
 import type * as Domain from "./Domain.js"
 
-type Printable =
-  | Domain.Class
-  | Domain.Constant
-  | Domain.Export
-  | Domain.Function
-  | Domain.Interface
-  | Domain.TypeAlias
-  | Domain.Namespace
-
 const createHeaderPrinter = (level: number) => (content: string): string =>
   "#".repeat(level) + " " + content + "\n\n"
 
@@ -65,6 +56,28 @@ const printExamples = (es: ReadonlyArray<string>): string =>
     )
     .join("\n\n")
 
+const printImportDescription = (
+  projectName: string,
+  module: Domain.Module,
+  method: string
+): string => {
+  const namespace = module.path.slice(1).join("/").replace(/\.ts$/, "")
+
+  return (
+    MarkdownPrinter.paragraph(
+      `To import and use \`${method}\` from the "${module.name}" module:`
+    ) +
+    MarkdownPrinter.paragraph(
+      MarkdownPrinter.fence(
+        "ts",
+        `import * as ${module.name} from "${projectName}/${namespace}"
+    // Can be accessed like this
+    ${module.name}.${method}`
+      )
+    )
+  )
+}
+
 const printStaticMethod = (m: Domain.Method): string =>
   MarkdownPrinter.paragraph(
     MarkdownPrinter.h3(printTitle(m.name, m.deprecated, "(static method)")),
@@ -223,7 +236,7 @@ export const printNamespace = (ns: Domain.Namespace, indentation: number): strin
   )
 
 /** @internal */
-export const print = (p: Printable): string => {
+export const print = (p: Domain.Printable): string => {
   switch (p._tag) {
     case "Class":
       return printClass(p)
@@ -242,8 +255,8 @@ export const print = (p: Printable): string => {
   }
 }
 
-const getPrintables = (module: Domain.Module): ReadonlyArray<Printable> =>
-  ReadonlyArray.flatten<Printable>([
+const getPrintables = (module: Domain.Module): ReadonlyArray<Domain.Printable> =>
+  ReadonlyArray.flatten<Domain.Printable>([
     module.classes,
     module.constants,
     module.exports,
@@ -295,7 +308,7 @@ export const printModule = (
             ReadonlyArray.sort(
               Order.mapInput(
                 String.Order,
-                (printable: Printable) => printable.name
+                (printable: Domain.Printable) => printable.name
               )
             ),
             ReadonlyArray.map(print)
@@ -331,6 +344,29 @@ export const printModule = (
     ))
   })
 
+/**
+ * @category printers
+ * @since 1.0.0
+ */
+export const printPrintableForAI = (
+  projectName: string,
+  module: Domain.Module,
+  printable: Domain.Printable
+) =>
+  prettify(
+    [
+      MarkdownPrinter.h1(printable.name),
+      printDescription(printable.description),
+      printImportDescription(projectName, module, printable.name),
+      printExamples(printable.examples),
+      printable._tag === "Function"
+        ? printSignatures(printable.signatures)
+        : printable._tag === "Constant"
+        ? printSignature(printable.signature)
+        : ""
+    ].join("\n")
+  )
+
 const defaultPrettierOptions: Prettier.Options = {
   parser: "markdown",
   semi: false,

test/Parser.ts

@@ -21,6 +21,7 @@ const defaultConfig: Config.Config = {
   srcDir: "src",
   outDir: "docs",
   theme: "pmarsceill/just-the-docs",
+  enableAI: true,
   enableSearch: true,
   enforceDescriptions: false,
   enforceExamples: false,