From d9ce8d2da92f1df0f35e29248dc8176fd59e2116 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 19 Jun 2024 22:20:28 +0200 Subject: [PATCH 1/3] chore: replace obsolete mentions of typedoc (#2957) --- .gitignore | 1 - scripts/apidocs/utils/format.ts | 4 ++-- tsconfig.json | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index d50069baccf..2d3321a37d5 100644 --- a/.gitignore +++ b/.gitignore @@ -77,7 +77,6 @@ versions.json /dist /docs/.vitepress/cache /docs/.vitepress/dist -/docs/api/typedoc.json /docs/public/api-diff-index.json /lib diff --git a/scripts/apidocs/utils/format.ts b/scripts/apidocs/utils/format.ts index ab9f524d2d2..c6c07ee637d 100644 --- a/scripts/apidocs/utils/format.ts +++ b/scripts/apidocs/utils/format.ts @@ -3,7 +3,7 @@ import { format } from 'prettier'; import prettierConfig from '../../../.prettierrc.js'; /** - * Formats markdown contents. + * Formats Markdown contents. * * @param text The text to format. */ @@ -12,7 +12,7 @@ export async function formatMarkdown(text: string): Promise { } /** - * Formats typedoc contents. + * Formats TypeScript contents. * * @param text The text to format. */ diff --git a/tsconfig.json b/tsconfig.json index 6d3b09b3e82..cc4809dab5d 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -17,7 +17,7 @@ "exclude": [ "node_modules", "dist", - // required for the typedoc related tests on macOS #2280 + // required for the signature related tests on macOS #2280 "test/scripts/apidocs/temp" ] } From 75841a55f1aaa8058d8e43c224330c7fa887549d Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 19 Jun 2024 22:25:50 +0200 Subject: [PATCH 2/3] docs: format signature with prettier (#2956) --- scripts/apidocs/output/page.ts | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/scripts/apidocs/output/page.ts b/scripts/apidocs/output/page.ts index ae1c3c4f6e7..9f3c87f7973 100644 --- a/scripts/apidocs/output/page.ts +++ b/scripts/apidocs/output/page.ts @@ -3,7 +3,7 @@ import { resolve } from 'node:path'; import type { ApiDocsMethod } from '../../../docs/.vitepress/components/api-docs/method'; import type { RawApiDocsPage } from '../processing/class'; import type { RawApiDocsMethod } from '../processing/method'; -import { formatMarkdown } from '../utils/format'; +import { formatMarkdown, formatTypescript } from '../utils/format'; import { adjustUrls, codeToHtml, mdToHtml } from '../utils/markdown'; import { FILE_PATH_API_DOCS } from '../utils/paths'; import { required } from '../utils/value-checks'; @@ -33,7 +33,7 @@ export async function writePages(pages: RawApiDocsPage[]): Promise { async function writePage(page: RawApiDocsPage): Promise { try { await writePageMarkdown(page); - writePageJsonData(page); + await writePageJsonData(page); } catch (error) { throw new Error(`Error writing page ${page.title}`, { cause: error }); } @@ -98,10 +98,12 @@ async function writePageMarkdown(page: RawApiDocsPage): Promise { * * @param page The page to write. */ -function writePageJsonData(page: RawApiDocsPage): void { +async function writePageJsonData(page: RawApiDocsPage): Promise { const { camelTitle, methods } = page; const pageData: Record = Object.fromEntries( - methods.map((method) => [method.name, toMethodData(method)]) + await Promise.all( + methods.map(async (method) => [method.name, await toMethodData(method)]) + ) ); const content = JSON.stringify(pageData, null, 2); @@ -110,7 +112,7 @@ function writePageJsonData(page: RawApiDocsPage): void { const defaultCommentRegex = /\s+Defaults to `([^`]+)`\..*/; -function toMethodData(method: RawApiDocsMethod): ApiDocsMethod { +async function toMethodData(method: RawApiDocsMethod): Promise { const { name, signatures, source } = method; const signatureData = required(signatures.at(-1), 'method signature'); const { @@ -125,6 +127,8 @@ function toMethodData(method: RawApiDocsMethod): ApiDocsMethod { seeAlsos, } = signatureData; const { filePath, line } = source; + let formattedSignature = await formatTypescript(signature); + formattedSignature = formattedSignature.trim(); /* Target order, omitted to improve diff to old files return { @@ -161,7 +165,7 @@ function toMethodData(method: RawApiDocsMethod): ApiDocsMethod { sourcePath: `${filePath}#L${line}`, throws: throws.length === 0 ? undefined : mdToHtml(throws.join('\n'), true), returns: returns.text, - examples: codeToHtml([signature, ...examples].join('\n')), + examples: codeToHtml([formattedSignature, ...examples].join('\n')), deprecated: mdToHtml(deprecated), seeAlsos: seeAlsos.map((seeAlso) => mdToHtml(seeAlso, true)), }; From 909ea01a6cc9f4753aeba45ba9e7bd1726e68916 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Thu, 20 Jun 2024 08:11:30 +0200 Subject: [PATCH 3/3] docs: fix whitespace in CONTRIBUTING.md (#2955) --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd8c2f90e92..487c99e0b03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ This is a shorthand for running the following scripts in order: - `pnpm run build:clean` - removes artifacts from previous builds - `pnpm run build:code` - builds the code, both CommonJS and ESM versions - `pnpm run build:types` - builds the TypeScript type definitions -- `pnpm run test:update-snapshots ` - runs all tests, and updates any snapshots if needed +- `pnpm run test:update-snapshots` - runs all tests, and updates any snapshots if needed - `pnpm run ts-check` - checks that there are no TypeScript errors in any files ## Good to know