From: Eduardo San Martin Morote Date: Fri, 18 Jul 2025 16:35:15 +0000 (+0200) Subject: docs: upgrade typedoc X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bce94866f2f87162b1f2d0cf0f53c25e1be477c7;p=thirdparty%2Fvuejs%2Frouter.git docs: upgrade typedoc --- diff --git a/packages/docs/.gitignore b/packages/docs/.gitignore index 4f2fc4ac..45f54803 100644 --- a/packages/docs/.gitignore +++ b/packages/docs/.gitignore @@ -1 +1,2 @@ .vitepress/cache +api diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts index b4e7f0e4..e93f5169 100644 --- a/packages/docs/.vitepress/config/en.ts +++ b/packages/docs/.vitepress/config/en.ts @@ -1,4 +1,5 @@ import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress' +import typedocSidebar from '../../api/typedoc-sidebar.json' export const META_URL = 'https://router.vuejs.org' export const META_TITLE = 'Vue Router' @@ -53,6 +54,12 @@ export const enConfig: LocaleSpecificConfig = { ], sidebar: { + '/api/': [ + { + text: 'API', + items: typedocSidebar, + }, + ], // catch-all fallback '/': [ { @@ -179,13 +186,6 @@ export const enConfig: LocaleSpecificConfig = { ], }, ], - - '/api/': [ - { - text: 'packages', - items: [{ text: 'vue-router', link: '/api/' }], - }, - ], }, }, } diff --git a/packages/docs/.vitepress/config/zh.ts b/packages/docs/.vitepress/config/zh.ts index dbc6ba4a..312f9784 100644 --- a/packages/docs/.vitepress/config/zh.ts +++ b/packages/docs/.vitepress/config/zh.ts @@ -1,4 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress' +import typedocSidebar from '../../api/typedoc-sidebar.json' +// TODO: rework the typedoc sidebar to include the /zh/ prefix export const META_URL = 'https://router.vuejs.org' export const META_TITLE = 'Vue Router' @@ -57,6 +59,12 @@ export const zhConfig: LocaleSpecificConfig = { ], sidebar: { + '/zh/api/': [ + { + text: 'API', + items: typedocSidebar, + }, + ], '/zh/': [ { text: '设置', @@ -186,13 +194,6 @@ export const zhConfig: LocaleSpecificConfig = { ], }, ], - - '/zh/api/': [ - { - text: 'packages', - items: [{ text: 'vue-router', link: '/zh/api/' }], - }, - ], }, }, } diff --git a/packages/docs/package.json b/packages/docs/package.json index 4765889c..05815c56 100644 --- a/packages/docs/package.json +++ b/packages/docs/package.json @@ -14,8 +14,9 @@ }, "dependencies": { "simple-git": "^3.28.0", + "typedoc-vitepress-theme": "^1.1.2", "vitepress": "1.6.3", - "vitepress-translation-helper": "^0.2.1", + "vitepress-translation-helper": "^0.2.2", "vue-router": "workspace:*" } } diff --git a/packages/docs/run-typedoc.mjs b/packages/docs/run-typedoc.mjs index 790b14b9..60c398e3 100644 --- a/packages/docs/run-typedoc.mjs +++ b/packages/docs/run-typedoc.mjs @@ -1,15 +1,21 @@ import path from 'node:path' -import { fileURLToPath } from 'node:url' import { createTypeDocApp } from './typedoc-markdown.mjs' -const __dirname = path.dirname(fileURLToPath(import.meta.url)) +const __dirname = path.dirname(new URL(import.meta.url).pathname) createTypeDocApp({ - name: 'API Documentation', + textContentMappings: { + 'title.indexPage': 'API Reference', + 'title.memberPage': '{name}', + }, tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'), + // entryPointStrategy: 'packages', categorizeByGroup: true, githubPages: false, - disableSources: true, // some links are in node_modules and it's ugly - plugin: ['typedoc-plugin-markdown'], + readme: 'none', + indexFormat: 'table', + disableSources: true, + plugin: ['typedoc-plugin-markdown', 'typedoc-vitepress-theme'], + useCodeBlocks: true, entryPoints: [path.resolve(__dirname, '../router/src/index.ts')], }).then(app => app.build()) diff --git a/packages/docs/typedoc-markdown.mjs b/packages/docs/typedoc-markdown.mjs index 3c84b4e3..dcae3a8a 100644 --- a/packages/docs/typedoc-markdown.mjs +++ b/packages/docs/typedoc-markdown.mjs @@ -1,13 +1,12 @@ // @ts-check import fs from 'node:fs/promises' import path from 'node:path' -import { fileURLToPath } from 'node:url' -import { Application, PageEvent, TSConfigReader } from 'typedoc' +import { Application, TSConfigReader, PageEvent } from 'typedoc' -const __dirname = path.dirname(fileURLToPath(import.meta.url)) +const __dirname = path.dirname(new URL(import.meta.url).pathname) +/** @satisfies {Partial} */ const DEFAULT_OPTIONS = { - // disableOutputCheck: true, cleanOutputDir: true, excludeInternal: false, readme: 'none', @@ -72,7 +71,7 @@ export async function createTypeDocApp(config = {}) { if (project) { // Rendered docs try { - await app.generateDocs(project, options.out) + await app.generateOutputs(project) app.logger.info(`generated at ${options.out}.`) } catch (error) { app.logger.error(error) @@ -88,6 +87,12 @@ export async function createTypeDocApp(config = {}) { } } +/** + * checks if a path exists + * + * @async + * @param {string} path + */ async function exists(path) { try { await fs.access(path) @@ -108,7 +113,7 @@ async function exists(path) { */ function prependYAML(contents, vars) { return contents - .replace(/^/, `${toYAML(vars)}\n\n`) + .replace(/^/, toYAML(vars) + '\n\n') .replace(/[\r\n]{3,}/g, '\n\n') } diff --git a/packages/docs/typedoc.tsconfig.json b/packages/docs/typedoc.tsconfig.json index 3ca328f8..4601fbf4 100644 --- a/packages/docs/typedoc.tsconfig.json +++ b/packages/docs/typedoc.tsconfig.json @@ -31,6 +31,6 @@ "removeComments": false, "jsx": "preserve", "lib": ["esnext", "dom"], - "types": ["node"] + "types": ["vitest", "node", "vite/client"] } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ca41b93a..828d69a7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -65,12 +65,15 @@ importers: simple-git: specifier: ^3.28.0 version: 3.28.0 + typedoc-vitepress-theme: + specifier: ^1.1.2 + version: 1.1.2(typedoc-plugin-markdown@4.7.0(typedoc@0.28.7(typescript@5.8.3))) vitepress: specifier: 1.6.3 version: 1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3) vitepress-translation-helper: - specifier: ^0.2.1 - version: 0.2.1(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)) + specifier: ^0.2.2 + version: 0.2.2(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)) vue-router: specifier: workspace:* version: link:../router @@ -4211,6 +4214,11 @@ packages: peerDependencies: typedoc: 0.28.x + typedoc-vitepress-theme@1.1.2: + resolution: {integrity: sha512-hQvCZRr5uKDqY1bRuY1+eNTNn6d4TE4OP5pnw65Y7WGgajkJW9X1/lVJK2UJpcwCmwkdjw1QIO49H9JQlxWhhw==} + peerDependencies: + typedoc-plugin-markdown: '>=4.4.0' + typedoc@0.28.7: resolution: {integrity: sha512-lpz0Oxl6aidFkmS90VQDQjk/Qf2iw0IUvFqirdONBdj7jPSN9mGXhy66BcGNDxx5ZMyKKiBVAREvPEzT6Uxipw==} engines: {node: '>= 18', pnpm: '>= 10'} @@ -4342,8 +4350,8 @@ packages: terser: optional: true - vitepress-translation-helper@0.2.1: - resolution: {integrity: sha512-zYjakGIdVDonT1P85OkeQcdE6e8vdmKiVclHB7DGcTzFUwb2D0w+hcC31AGneB5wa5IiqEoipycSTYNKM0YKJg==} + vitepress-translation-helper@0.2.2: + resolution: {integrity: sha512-xqE4p1iUmsADKyA8W/02POtEwL0ZMcY2Ogj4Shuh70392UslB5JhrgCdF1j61NIQhgy/wgAGhn33QZdksN6IqQ==} hasBin: true peerDependencies: vitepress: ^1.0.0 @@ -8659,6 +8667,10 @@ snapshots: dependencies: typedoc: 0.28.7(typescript@5.8.3) + typedoc-vitepress-theme@1.1.2(typedoc-plugin-markdown@4.7.0(typedoc@0.28.7(typescript@5.8.3))): + dependencies: + typedoc-plugin-markdown: 4.7.0(typedoc@0.28.7(typescript@5.8.3)) + typedoc@0.28.7(typescript@5.8.3): dependencies: '@gerrit0/mini-shiki': 3.8.0 @@ -8790,7 +8802,7 @@ snapshots: fsevents: 2.3.3 terser: 5.43.1 - vitepress-translation-helper@0.2.1(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)): + vitepress-translation-helper@0.2.2(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)): dependencies: minimist: 1.2.8 simple-git: 3.28.0