docs: add api gen

Author: posva

.gitignore

@@ -10,3 +10,4 @@ package-lock.json
 temp
 roadmap.md
 *-debug.log
+docs/api

package.json

@@ -28,7 +28,8 @@
   "funding": "https://github.com/sponsors/posva",
   "scripts": {
     "docs": "vitepress dev docs --port 3000",
-    "docs:build": "vitepress build docs",
+    "docs:build": "pnpm run docs:api:build && vitepress build docs",
+    "docs:api:build": "node ./scripts/run-typedoc.cjs",
     "build": "unbuild",
     "release": "node scripts/release.mjs",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 1",
@@ -82,6 +83,8 @@
     "p-series": "^3.0.0",
     "prettier": "^2.0.5",
     "semver": "^7.3.8",
+    "typedoc": "^0.23.17",
+    "typedoc-plugin-markdown": "^3.13.6",
     "typescript": "~4.8.4",
     "unbuild": "^0.9.4",
     "vitepress": "1.0.0-alpha.21",

pnpm-lock.yaml

@@ -0,0 +1,11 @@
+const { createTypeDocApp } = require('./typedoc-markdown.cjs')
+const path = require('path')
+
+createTypeDocApp({
+  name: 'API Documentation',
+  tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'),
+  // entryPointStrategy: 'packages',
+  githubPages: false,
+  disableSources: true,
+  entryPoints: [path.resolve(__dirname, '../src/index.ts')],
+}).build()

scripts/run-typedoc.cjs

@@ -0,0 +1,114 @@
+const _fs = require('fs')
+const path = require('path')
+const TypeDoc = require('typedoc')
+const { PageEvent } = TypeDoc
+const {
+  prependYAML,
+} = require('typedoc-plugin-markdown/dist/utils/front-matter')
+
+const fs = _fs.promises
+
+const DEFAULT_OPTIONS = {
+  // disableOutputCheck: true,
+  cleanOutputDir: true,
+  excludeInternal: true,
+  readme: 'none',
+  out: path.resolve(__dirname, '../docs/api'),
+  entryDocument: 'index.md',
+  hideBreadcrumbs: false,
+  hideInPageTOC: true,
+}
+
+/**
+ *
+ * @param {Partial<import('typedoc').TypeDocOptions>} config
+ */
+exports.createTypeDocApp = function createTypeDocApp(config = {}) {
+  const options = {
+    ...DEFAULT_OPTIONS,
+    ...config,
+  }
+
+  const app = new TypeDoc.Application()
+
+  // If you want TypeDoc to load tsconfig.json / typedoc.json files
+  app.options.addReader(new TypeDoc.TSConfigReader())
+  // app.options.addReader(new TypeDoc.TypeDocReader())
+
+  /** @type {'build' | 'serve'} */
+  let targetMode = 'build'
+
+  app.renderer.on(
+    PageEvent.END,
+    /**
+     *
+     * @param {import('typedoc/dist/lib/output/events').PageEvent} page
+     */
+    (page) => {
+      if (page.url !== 'index.md' && page.contents) {
+        page.contents = prependYAML(page.contents, {
+          sidebar: 'auto',
+          // TODO: figure out a way to point to the source files?
+          editLinks: false,
+          sidebarDepth: 3,
+        })
+      }
+    }
+  )
+
+  async function serve() {
+    app.bootstrap(options)
+    app.convertAndWatch(handleProject)
+  }
+
+  async function build() {
+    if (
+      (await exists(options.out)) &&
+      (await fs.stat(options.out)).isDirectory()
+    ) {
+      await fs.rm(options.out, { recursive: true })
+    }
+    app.bootstrap(options)
+    const project = app.convert()
+    return handleProject(project)
+  }
+
+  /**
+   *
+   * @param {import('typedoc').ProjectReflection} project
+   */
+  async function handleProject(project) {
+    if (project) {
+      // Rendered docs
+      try {
+        await app.generateDocs(project, options.out)
+        app.logger.info(`generated at ${options.out}.`)
+      } catch (error) {
+        app.logger.error(error)
+      }
+    } else {
+      app.logger.error('No project')
+    }
+  }
+
+  return {
+    build,
+    serve,
+    /**
+     *
+     * @param {'build' | 'serve'} command
+     */
+    setTargetMode(command) {
+      targetMode = command
+    },
+  }
+}
+
+async function exists(path) {
+  try {
+    await fs.access(path)
+    return true
+  } catch {
+    return false
+  }
+}

scripts/typedoc-markdown.cjs

@@ -0,0 +1,35 @@
+{
+  "include": ["../src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "..",
+    "outDir": "dist",
+    "sourceMap": false,
+    "noEmit": true,
+    "paths": {
+      "vuefire": ["../src"]
+    },
+
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "allowJs": false,
+    "skipLibCheck": true,
+
+    "noUnusedLocals": false,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": false,
+    "strict": true,
+    "isolatedModules": true,
+
+    "experimentalDecorators": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "removeComments": false,
+    "jsx": "preserve",
+    "lib": ["esnext", "dom"]
+  }
+}

scripts/typedoc.tsconfig.json

@@ -31,7 +31,7 @@ export interface FirestoreOptions {
   snapshotOptions?: SnapshotOptions
 
   /**
-   * @inheritdoc {SnapshotListenOptions}
+   * @inheritDoc {SnapshotListenOptions}
    */
   snapshotListenOptions?: SnapshotListenOptions