docs: add generated api docs

diff --git a/.gitignore b/.gitignore
index c49e5d412ab0d69474b357c239e42f7fd6b0589b..d435e48e43043188a11e06a0037575ca0d130f42 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@ test-dts/tsconfig.tsbuildinfo
 packages/*/LICENSE
 explorations
 docs-api
+packages/docs/api

diff --git a/netlify.toml b/netlify.toml
index b24cbdcea93e8dfc0785bc0fb7f35afefc68ee62..ab1e137dfe741f28aadd2c6267362b57d20e6cba 100644 (file)
--- a/netlify.toml
+++ b/netlify.toml
@@ -1,4 +1,4 @@
 [build]
-command = "yarn run docs:build && yarn run docs:api"
+command = "yarn run docs:api && yarn run docs:build"
 ignore = "./scripts/docs-check.sh"
 publish = "packages/docs/.vitepress/dist"

diff --git a/package.json b/package.json
index 24f3719948b60922d87641be3c90b6a6de3d12db..b3ff3dab6ec08d9cd84eab548aee8cbba7e8bd1e 100644 (file)
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
     "test:jest": "jest --coverage",
     "test:types": "tsc --build ./tsconfig.json",
     "test:dts": "lerna run test:dts",
-    "docs:api": "typedoc"
+    "docs:api": "lerna run docs:api --scope @pinia/docs"
   },
   "devDependencies": {
     "@rollup/plugin-alias": "^3.1.5",
@@ -50,6 +50,7 @@
     "rollup-plugin-typescript2": "^0.30.0",
     "semver": "^7.3.5",
     "typedoc": "^0.21.6",
+    "typedoc-plugin-markdown": "^3.10.4",
     "typescript": "^4.3.5",
     "yorkie": "^2.0.0"
   },

diff --git a/packages/docs/.vitepress/config.js b/packages/docs/.vitepress/config.js
index 07a54bb871207fc8db652f4af3a15dfa567bcce4..04ad82970ad4c67e170677534ecae06d728a7b9a 100644 (file)
--- a/packages/docs/.vitepress/config.js
+++ b/packages/docs/.vitepress/config.js
@@ -143,7 +143,7 @@ module.exports = {
 
     nav: [
       { text: 'Guide', link: '/introduction.html' },
-      { text: 'API', link: 'https://pinia.esm.dev/api/' },
+      { text: 'API', link: '/api/' },
       // { text: 'Config', link: '/config/' },
       // { text: 'Plugins', link: '/plugins/' },
       {

diff --git a/packages/docs/package.json b/packages/docs/package.json
index e0bbe98cc7623c2a72e2dee4d85a34dde6660d1e..ef66b6d1daf6371b51d10619d4a5885389e7d379 100644 (file)
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "docs": "vitepress dev .",
+    "docs:api": "node run-typedoc.js",
     "docs:build": "vitepress build ."
   },
   "dependencies": {

diff --git a/packages/docs/run-typedoc.js b/packages/docs/run-typedoc.js
new file mode 100644 (file)
index 0000000..e428151
--- /dev/null
+++ b/packages/docs/run-typedoc.js
@@ -0,0 +1,11 @@
+const { createTypeDocApp } = require('./typedoc-markdown')
+const path = require('path')
+
+createTypeDocApp({
+  name: 'Pinia',
+  entryPoints: [
+    path.resolve(__dirname, '../pinia/src/index.ts'),
+    path.resolve(__dirname, '../testing/src/index.ts'),
+    path.resolve(__dirname, '../nuxt/src/index.ts'),
+  ],
+}).build()

diff --git a/packages/docs/typedoc-markdown.js b/packages/docs/typedoc-markdown.js
new file mode 100644 (file)
index 0000000..75453e3
--- /dev/null
+++ b/packages/docs/typedoc-markdown.js
@@ -0,0 +1,98 @@
+const _fs = require('fs')
+const path = require('path')
+const TypeDoc = require('typedoc')
+const { PageEvent } = require('typedoc/dist/lib/output/events')
+const {
+  prependYAML,
+} = require('typedoc-plugin-markdown/dist/utils/front-matter')
+
+const fs = _fs.promises
+
+const DEFAULT_OPTIONS = {
+  disableOutputCheck: true,
+  readme: 'none',
+  out: path.resolve(__dirname, './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',
+          sidebarDepth: 3,
+        })
+      }
+    }
+  )
+
+  async function serve() {
+    app.bootstrap(options)
+    app.convertAndWatch(handleProject)
+  }
+
+  async function build() {
+    if ((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
+    },
+  }
+}

diff --git a/packages/docs/vite-typedoc-plugin.ts b/packages/docs/vite-typedoc-plugin.ts
new file mode 100644 (file)
index 0000000..006b644
--- /dev/null
+++ b/packages/docs/vite-typedoc-plugin.ts
@@ -0,0 +1,19 @@
+import { Plugin } from 'vite'
+import _fs from 'fs'
+import { TypeDocOptions } from 'typedoc'
+import { createTypeDocApp } from './typedoc-markdown'
+
+export default function TypeDocPlugin(
+  config: Partial<TypeDocOptions> = {}
+): Plugin {
+  const { serve, setTargetMode } = createTypeDocApp(config)
+  setTargetMode('serve')
+
+  return {
+    name: 'typedoc',
+    apply: 'serve',
+    buildStart() {
+      return serve()
+    },
+  }
+}

diff --git a/packages/docs/vite.config.ts b/packages/docs/vite.config.ts
index 53da4b0d217f520efe28c439d0138ada4fb30000..3bf412d4a8a63598d13fdb2c487ff0fc586e62b2 100644 (file)
--- a/packages/docs/vite.config.ts
+++ b/packages/docs/vite.config.ts
@@ -1,11 +1,24 @@
 import { defineConfig, Plugin } from 'vite'
 import _fs from 'fs'
 import path from 'path'
+// import TypeDocPlugin from './vite-typedoc-plugin'
 
 const fs = _fs.promises
 
 export default defineConfig({
-  plugins: process.env.NETLIFY ? [] : [copyPiniaPlugin()],
+  clearScreen: false,
+  plugins: [
+    ...(process.env.NETLIFY ? [] : [copyPiniaPlugin()]),
+    // FIXME: fix vitepress bug of running plugins twice
+    // TypeDocPlugin({
+    //   name: 'Pinia',
+    //   entryPoints: [
+    //     path.resolve(__dirname, '../pinia/src/index.ts'),
+    //     path.resolve(__dirname, '../testing/src/index.ts'),
+    //     path.resolve(__dirname, '../nuxt/src/index.ts'),
+    //   ],
+    // }),
+  ],
   define: {
     __DEV__: 'true',
     __BROWSER__: 'true',

diff --git a/packages/pinia/src/types.ts b/packages/pinia/src/types.ts
index 1eb8b2a8a1262a9c93515ab6cc8332371af109c8..0196e28c048a95a421fa3aec4a9d8fe3173c63ba 100644 (file)
--- a/packages/pinia/src/types.ts
+++ b/packages/pinia/src/types.ts
@@ -658,7 +658,8 @@ export interface DefineStoreOptions<
   id: Id
 
   /**
-   * Function to create a fresh state.
+   * Function to create a fresh state. **Must be an arrow function** to ensure
+   * correct typings!
    */
   state?: () => S
 

diff --git a/typedoc.js b/typedoc.js
deleted file mode 100644 (file)
index 9c57e13..0000000
--- a/typedoc.js
+++ /dev/null
@@ -1,16 +0,0 @@
-// @ts-check
-
-/** @type {Partial<import('typedoc').TypeDocOptions>} */
-const config = {
-  name: 'Pinia',
-  readme: 'none',
-  excludeInternal: true,
-  out: 'packages/docs/.vitepress/dist/api',
-  entryPoints: [
-    'packages/pinia/src/index.ts',
-    'packages/testing/src/index.ts',
-    'packages/nuxt/src/index.ts',
-  ],
-}
-
-module.exports = config

diff --git a/yarn.lock b/yarn.lock
index 6b2bb33878c7bd951cf132f3e4fd02ab1ede1d5d..c4d9fa7a23668bce7b4c2b05ddd72874e0f7eadc 100644 (file)
--- a/yarn.lock
+++ b/yarn.lock
@@ -8242,6 +8242,13 @@ typedoc-default-themes@^0.12.10:
   resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.12.10.tgz#614c4222fe642657f37693ea62cad4dafeddf843"
   integrity sha512-fIS001cAYHkyQPidWXmHuhs8usjP5XVJjWB8oZGqkTowZaz3v7g3KDZeeqE82FBrmkAnIBOY3jgy7lnPnqATbA==
 
+typedoc-plugin-markdown@^3.10.4:
+  version "3.10.4"
+  resolved "https://registry.yarnpkg.com/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.10.4.tgz#4e0e9c584a1e421beafa4c3666896615f069da6b"
+  integrity sha512-if9w7S9fXLg73AYi/EoRSEhTOZlg3I8mIP8YEmvzSE33VrNXC9/hA0nVcLEwFVJeQY7ay6z67I6kW0KIv7LjeA==
+  dependencies:
+    handlebars "^4.7.7"
+
 typedoc@^0.21.6:
   version "0.21.6"
   resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.21.6.tgz#854bfa2d6b3ac818ac70aa4734a4d1ba93695595"