docs: update api generation

Author: posva

package.json

@@ -34,8 +34,8 @@
     "p-series": "^3.0.0",
     "prettier": "^2.8.8",
     "semver": "^7.5.4",
-    "typedoc": "^0.24.8",
-    "typedoc-plugin-markdown": "^3.15.4",
+    "typedoc": "^0.25.3",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "~5.1.6",
     "yorkie": "^2.0.0"
   },

packages/docs/run-typedoc.js renamed to packages/docs/run-typedoc.mjs

@@ -1,12 +1,15 @@
-const { createTypeDocApp } = require('./typedoc-markdown')
-const path = require('path')
+import path from 'node:path'
+import { createTypeDocApp } from './typedoc-markdown.mjs'
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 createTypeDocApp({
   name: 'API Documentation',
   tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'),
   // entryPointStrategy: 'packages',
+  categorizeByGroup: true,
   githubPages: false,
-  plugin: ['typedoc-plugin-markdown'],
   disableSources: true,
+  plugin: ['typedoc-plugin-markdown'],
   entryPoints: [path.resolve(__dirname, '../router/src/index.ts')],
-}).build()
+}).then(app => app.build())

packages/docs/typedoc-markdown.js renamed to packages/docs/typedoc-markdown.mjs

@@ -1,9 +1,9 @@
-const _fs = require('fs')
-const path = require('path')
-const TypeDoc = require('typedoc')
-const { PageEvent } = TypeDoc
+// @ts-check
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { Application, TSConfigReader, PageEvent } from 'typedoc'
 
-const fs = _fs.promises
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 const DEFAULT_OPTIONS = {
   // disableOutputCheck: true,
@@ -12,33 +12,36 @@ const DEFAULT_OPTIONS = {
   readme: 'none',
   out: path.resolve(__dirname, './api'),
   entryDocument: 'index.md',
-  preserveAnchorCasing: true,
   hideBreadcrumbs: false,
   hideInPageTOC: true,
+  preserveAnchorCasing: true,
 }
 
 /**
  *
  * @param {Partial<import('typedoc').TypeDocOptions>} config
  */
-exports.createTypeDocApp = function createTypeDocApp(config = {}) {
+export async function createTypeDocApp(config = {}) {
   const options = {
     ...DEFAULT_OPTIONS,
     ...config,
   }
 
-  const app = new TypeDoc.Application()
+  const app = await Application.bootstrapWithPlugins(options)
 
   // If you want TypeDoc to load tsconfig.json / typedoc.json files
-  app.options.addReader(new TypeDoc.TSConfigReader())
+  app.options.addReader(new TSConfigReader())
 
   app.renderer.on(
     PageEvent.END,
     /**
      *
-     * @param {import('typedoc/dist/lib/output/events').PageEvent} page
+     * @param {import('typedoc').PageEvent} page
      */
     page => {
+      if (!page.contents) {
+        return
+      }
       page.contents = prependYAML(page.contents, {
         // TODO: figure out a way to point to the source files?
         editLink: false,
@@ -47,7 +50,6 @@ exports.createTypeDocApp = function createTypeDocApp(config = {}) {
   )
 
   async function serve() {
-    await app.bootstrapWithPlugins(options)
     app.convertAndWatch(handleProject)
   }
 
@@ -58,14 +60,13 @@ exports.createTypeDocApp = function createTypeDocApp(config = {}) {
     ) {
       await fs.rm(options.out, { recursive: true })
     }
-    await app.bootstrapWithPlugins(options)
-    const project = app.convert()
+    const project = await app.convert()
     return handleProject(project)
   }
 
   /**
    *
-   * @param {import('typedoc').ProjectReflection} project
+   * @param {import('typedoc').ProjectReflection | undefined} project
    */
   async function handleProject(project) {
     if (project) {
@@ -84,13 +85,6 @@ exports.createTypeDocApp = function createTypeDocApp(config = {}) {
   return {
     build,
     serve,
-    /**
-     *
-     * @param {'build' | 'serve'} command
-     */
-    setTargetMode(command) {
-      targetMode = command
-    },
   }
 }
 
@@ -102,6 +96,7 @@ async function exists(path) {
     return false
   }
 }
+
 /**
  * @typedef {Record<string, string | number | boolean>} FrontMatterVars
  */