feat(typedoc): Add generateReferenceDocs function (#132)

* feat(typedoc): Add reference doc generation

* Export packages type

* Rename type to Package

nx.json

@@ -14,9 +14,6 @@
     "test:build": {
       "cache": true
     },
-    "test:format": {
-      "cache": true
-    },
     "test:sherif": {
       "cache": true
     }

package.json

@@ -10,8 +10,8 @@
   "scripts": {
     "preinstall": "node -e \"if(process.env.CI == 'true') {console.log('Skipping preinstall...')} else {process.exit(1)}\" || npx -y only-allow pnpm",
     "test": "pnpm run test:ci",
-    "test:pr": "nx affected --targets=test:format,test:eslint,test:types,test:build,test:sherif",
-    "test:ci": "nx run-many --targets=test:format,test:eslint,test:types,test:build,test:sherif",
+    "test:pr": "nx affected --targets=test:eslint,test:types,test:build,test:sherif",
+    "test:ci": "nx run-many --targets=test:eslint,test:types,test:build,test:sherif",
     "test:build": "nx affected --target=test:build",
     "test:types": "nx affected --target=test:types",
     "test:eslint": "nx affected --target=test:eslint",
@@ -22,11 +22,6 @@
     "cipublish": "node ./packages/config/bin/config.js publish --cwd .",
     "cipublishforce": "CI=true pnpm cipublish"
   },
-  "nx": {
-    "includedScripts": [
-      "test:format"
-    ]
-  },
   "devDependencies": {
     "@types/node": "^20.14.10",
     "jsdom": "^24.1.0",

packages/config/package.json

@@ -32,6 +32,12 @@
         "default": "./src/publish/index.js"
       }
     },
+    "./typedoc": {
+      "import": {
+        "types": "./src/typedoc/index.d.ts",
+        "default": "./src/typedoc/index.js"
+      }
+    },
     "./vite": {
       "import": {
         "types": "./src/vite/index.d.ts",
@@ -68,6 +74,9 @@
     "rollup-plugin-preserve-directives": "^0.4.0",
     "semver": "^7.6.3",
     "simple-git": "^3.25.0",
+    "typedoc": "^0.26.4",
+    "typedoc-plugin-frontmatter": "^1.0.0",
+    "typedoc-plugin-markdown": "^4.2.1",
     "typescript-eslint": "^7.16.1",
     "v8flags": "^4.0.1",
     "vite-plugin-dts": "^3.9.1",

packages/config/src/publish/index.d.ts

@@ -1,4 +1,37 @@
-import type { RunOptions } from './types'
+export type Commit = {
+  hash: string
+  body: string
+  subject: string
+  author_name: string
+  author_email: string
+  type: string
+  scope: string | null | undefined
+}
+
+export type Package = {
+  name: string
+  packageDir: string
+}
+
+export type BranchConfig = {
+  prerelease: boolean
+  previousVersion?: boolean
+}
+
+export type Options = {
+  /** Contains config for publishable branches. */
+  branchConfigs: Record<string, BranchConfig>
+  /** List your npm packages here. The first package will be used as the versioner. */
+  packages: Array<Package>
+  /** Path to root directory of your project. */
+  rootDir: string
+  /** The branch to publish. Defaults to the current branch if none supplied. */
+  branch?: string
+  /** A manual tag to force release. Must start with `v` */
+  tag?: string
+  /** The GitHub token used to search for user metadata and make a GitHub release. */
+  ghToken?: string
+}
 
 /** https://tanstack.com/config/latest/docs/publish */
-export function publish(options: RunOptions): Promise<void>
+export function publish(options: Options): Promise<void>

packages/config/src/publish/index.js

@@ -18,7 +18,7 @@ import {
 
 /**
  * Execute a script being published
- * @param {import('./types.js').RunOptions} options
+ * @param {import('./index.js').Options} options
  * @returns {Promise<void>}
  */
 export const publish = async (options) => {
@@ -28,7 +28,7 @@ export const publish = async (options) => {
   const isMainBranch = branchName === 'main'
   const npmTag = isMainBranch ? 'latest' : branchName
 
-  /** @type {import('./types.js').BranchConfig | undefined} */
+  /** @type {import('./index.js').BranchConfig | undefined} */
   const branchConfig = branchConfigs[branchName]
 
   if (!branchConfig) {
@@ -115,7 +115,7 @@ export const publish = async (options) => {
 
   /**
    * Get the commits since the latest tag
-   * @type {import('./types.js').Commit[]}
+   * @type {import('./index.js').Commit[]}
    */
   const commitsSinceLatestTag = await Promise.all(
     rawCommitsLog.map(async (c) => {
@@ -273,7 +273,7 @@ export const publish = async (options) => {
           ...prev,
           [curr.type]: [...(prev[curr.type] ?? []), curr],
         }
-      }, /** @type {Record<string, import('./types.js').Commit[]>} */ ({})),
+      }, /** @type {Record<string, import('./index.js').Commit[]>} */ ({})),
     )
       .sort(
         getSorterFn(([type]) =>

packages/config/src/typedoc/index.d.ts

@@ -0,0 +1,16 @@
+import type { UserConfig } from 'vite'
+
+export type Package = {
+  name: string
+  entryPoints: Array<string>
+  tsconfig: string
+  outputDir: string
+  exclude?: Array<string>
+}
+
+export type Options = {
+  /** Config for packages that need reference docs */
+  packages: Array<Package>
+}
+
+export function generateReferenceDocs(config: Options): Promise<void>

packages/config/src/typedoc/index.js

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { mkdir, rm } from 'node:fs/promises'
+import * as TypeDoc from 'typedoc'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+/**
+ * @type {Partial<import("typedoc").TypeDocOptions & import("typedoc-plugin-markdown").PluginOptions>}
+ */
+const settings = {
+  plugin: [
+    'typedoc-plugin-markdown',
+    'typedoc-plugin-frontmatter',
+    resolve(__dirname, './typedoc-custom-settings.js'),
+  ],
+  hideGenerator: true,
+  readme: 'none',
+  flattenOutputFiles: true,
+  entryFileName: 'index',
+  hideBreadcrumbs: true,
+  hidePageHeader: true,
+  useCodeBlocks: true,
+  excludePrivate: true,
+}
+
+/**
+ * @param {import('./index.js').Options} options
+ * @returns {Promise<void>}
+ */
+export const generateReferenceDocs = async (options) => {
+  for (const pkg of options.packages) {
+    // Clean and recreate the output directories
+    try {
+      await rm(pkg.outputDir, { recursive: true })
+    } catch (error) {
+      // @ts-expect-error
+      if (error.code !== 'ENOENT') {
+        throw error
+      }
+    }
+    await mkdir(pkg.outputDir, { recursive: true })
+
+    const app = await TypeDoc.Application.bootstrapWithPlugins({
+      ...settings,
+      entryPoints: pkg.entryPoints,
+      tsconfig: pkg.tsconfig,
+      exclude: pkg.exclude,
+    })
+
+    const project = await app.convert()
+
+    if (project) {
+      await app.generateDocs(project, pkg.outputDir)
+    }
+  }
+}

packages/config/src/typedoc/typedoc-custom-settings.js

@@ -0,0 +1,39 @@
+import {
+  MarkdownPageEvent,
+  MarkdownRendererEvent,
+} from 'typedoc-plugin-markdown'
+
+/**
+ * @param {import("typedoc-plugin-markdown").MarkdownApplication} app
+ */
+export function load(app) {
+  // Add `id` and `title` to frontmatter
+  app.renderer.on(
+    MarkdownPageEvent.BEGIN,
+    /** @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page */
+    (page) => {
+      page.frontmatter = {
+        id: page.model.name,
+        title: page.model.name,
+      }
+    },
+  )
+  // Rename output files
+  app.renderer.on(
+    MarkdownRendererEvent.BEGIN,
+    /**
+     * @param {import("typedoc-plugin-markdown").MarkdownRendererEvent} renderer
+     */ (renderer) => {
+      renderer.urls = renderer.urls?.map((urlMapping) => {
+        const name = urlMapping.url.split('.')
+        if (name[0] !== 'index') {
+          name.splice(0, 1)
+        }
+        const newBasename = name.join('.')
+        urlMapping.url = newBasename
+        urlMapping.model.url = newBasename
+        return urlMapping
+      })
+    },
+  )
+}