From: Eduardo San Martin Morote Date: Wed, 8 Nov 2023 12:48:50 +0000 (+0100) Subject: docs: update api generation X-Git-Tag: v4.3.0~67 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a3a1b336b3bc6e5712f84df194bb2d15d1da5b46;p=thirdparty%2Fvuejs%2Frouter.git docs: update api generation --- diff --git a/package.json b/package.json index 36d98d83..18b9b5a7 100644 --- a/package.json +++ b/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" }, diff --git a/packages/docs/run-typedoc.js b/packages/docs/run-typedoc.mjs similarity index 59% rename from packages/docs/run-typedoc.js rename to packages/docs/run-typedoc.mjs index 720d5570..56633d8e 100644 --- a/packages/docs/run-typedoc.js +++ b/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()) diff --git a/packages/docs/typedoc-markdown.js b/packages/docs/typedoc-markdown.mjs similarity index 77% rename from packages/docs/typedoc-markdown.js rename to packages/docs/typedoc-markdown.mjs index 4e4d4ce3..89876024 100644 --- a/packages/docs/typedoc-markdown.js +++ b/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} 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} FrontMatterVars */ diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 12ce38c1..8644a816 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -35,11 +35,11 @@ importers: specifier: ^7.5.4 version: 7.5.4 typedoc: - specifier: ^0.24.8 - version: 0.24.8(typescript@5.1.6) + specifier: ^0.25.3 + version: 0.25.3(typescript@5.1.6) typedoc-plugin-markdown: - specifier: ^3.15.4 - version: 3.15.4(typedoc@0.24.8) + specifier: ^3.17.1 + version: 3.17.1(typedoc@0.25.3) typescript: specifier: ~5.1.6 version: 5.1.6 @@ -2403,13 +2403,8 @@ packages: engines: {node: '>=12'} dev: true - /ansi-sequence-parser@1.1.0: - resolution: {integrity: sha512-lEm8mt52to2fT8GhciPCGeCXACSz2UwIN4X2e2LJSnZ5uAbn2/dsYdOmUXq0AtWS5cpAupysIneExOgH0Vd2TQ==} - dev: true - /ansi-sequence-parser@1.1.1: resolution: {integrity: sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==} - dev: false /ansi-styles@3.2.1: resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==} @@ -6617,23 +6612,23 @@ packages: engines: {node: '>=8'} dev: true - /shiki@0.14.2: - resolution: {integrity: sha512-ltSZlSLOuSY0M0Y75KA+ieRaZ0Trf5Wl3gutE7jzLuIcWxLp5i/uEnLoQWNvgKXQ5OMpGkJnVMRLAuzjc0LJ2A==} + /shiki@0.14.3: + resolution: {integrity: sha512-U3S/a+b0KS+UkTyMjoNojvTgrBHjgp7L6ovhFVZsXmBGnVdQ4K4U9oK0z63w538S91ATngv1vXigHCSWOwnr+g==} dependencies: - ansi-sequence-parser: 1.1.0 + ansi-sequence-parser: 1.1.1 jsonc-parser: 3.2.0 vscode-oniguruma: 1.7.0 vscode-textmate: 8.0.0 - dev: true + dev: false - /shiki@0.14.3: - resolution: {integrity: sha512-U3S/a+b0KS+UkTyMjoNojvTgrBHjgp7L6ovhFVZsXmBGnVdQ4K4U9oK0z63w538S91ATngv1vXigHCSWOwnr+g==} + /shiki@0.14.5: + resolution: {integrity: sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw==} dependencies: ansi-sequence-parser: 1.1.1 jsonc-parser: 3.2.0 vscode-oniguruma: 1.7.0 vscode-textmate: 8.0.0 - dev: false + dev: true /signal-exit@3.0.7: resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==} @@ -7109,26 +7104,26 @@ packages: engines: {node: '>=10'} dev: true - /typedoc-plugin-markdown@3.15.4(typedoc@0.24.8): - resolution: {integrity: sha512-KpjFL/NDrQAbY147oIoOgob2vAdEchsMcTVd6+e6H2lC1l5xhi48bhP/fMJI7qYQ8th5nubervgqw51z7gY66A==} + /typedoc-plugin-markdown@3.17.1(typedoc@0.25.3): + resolution: {integrity: sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==} peerDependencies: typedoc: '>=0.24.0' dependencies: handlebars: 4.7.7 - typedoc: 0.24.8(typescript@5.1.6) + typedoc: 0.25.3(typescript@5.1.6) dev: true - /typedoc@0.24.8(typescript@5.1.6): - resolution: {integrity: sha512-ahJ6Cpcvxwaxfu4KtjA8qZNqS43wYt6JL27wYiIgl1vd38WW/KWX11YuAeZhuz9v+ttrutSsgK+XO1CjL1kA3w==} - engines: {node: '>= 14.14'} + /typedoc@0.25.3(typescript@5.1.6): + resolution: {integrity: sha512-Ow8Bo7uY1Lwy7GTmphRIMEo6IOZ+yYUyrc8n5KXIZg1svpqhZSWgni2ZrDhe+wLosFS8yswowUzljTAV/3jmWw==} + engines: {node: '>= 16'} hasBin: true peerDependencies: - typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x dependencies: lunr: 2.3.9 marked: 4.3.0 - minimatch: 9.0.1 - shiki: 0.14.2 + minimatch: 9.0.3 + shiki: 0.14.5 typescript: 5.1.6 dev: true