From 094fd82ec9b1f8f5fb92a129ec46432dcbbaf86f Mon Sep 17 00:00:00 2001 From: Eduardo San Martin Morote Date: Tue, 31 Aug 2021 23:29:57 +0200 Subject: [PATCH] docs: add generated api docs --- .gitignore | 1 + netlify.toml | 2 +- package.json | 3 +- packages/docs/.vitepress/config.js | 2 +- packages/docs/package.json | 1 + packages/docs/run-typedoc.js | 11 ++++ packages/docs/typedoc-markdown.js | 98 ++++++++++++++++++++++++++++ packages/docs/vite-typedoc-plugin.ts | 19 ++++++ packages/docs/vite.config.ts | 15 ++++- packages/pinia/src/types.ts | 3 +- typedoc.js | 16 ----- yarn.lock | 7 ++ 12 files changed, 157 insertions(+), 21 deletions(-) create mode 100644 packages/docs/run-typedoc.js create mode 100644 packages/docs/typedoc-markdown.js create mode 100644 packages/docs/vite-typedoc-plugin.ts delete mode 100644 typedoc.js diff --git a/.gitignore b/.gitignore index c49e5d41..d435e48e 100644 --- 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 b24cbdce..ab1e137d 100644 --- 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 24f37199..b3ff3dab 100644 --- 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 07a54bb8..04ad8297 100644 --- 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 e0bbe98c..ef66b6d1 100644 --- 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 index 00000000..e428151a --- /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 index 00000000..75453e3e --- /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} 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 index 00000000..006b644a --- /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 = {} +): 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 53da4b0d..3bf412d4 100644 --- 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 1eb8b2a8..0196e28c 100644 --- 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 index 9c57e136..00000000 --- a/typedoc.js +++ /dev/null @@ -1,16 +0,0 @@ -// @ts-check - -/** @type {Partial} */ -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 6b2bb338..c4d9fa7a 100644 --- 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" -- 2.47.3