From 92c82c3592240f5aefc81960fcf2ea2691c37247 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Tue, 24 Sep 2024 10:07:24 +0100 Subject: [PATCH] chore: roll documentation scripts --- src/documentation.js | 43 ++++++++---------------------------- src/generate.js | 24 +++++++++++++++++--- src/generator.js | 3 +-- src/sync_upstream_scripts.js | 21 +++++++++--------- 4 files changed, 41 insertions(+), 50 deletions(-) diff --git a/src/documentation.js b/src/documentation.js index fa575791559..f85dd5090c0 100644 --- a/src/documentation.js +++ b/src/documentation.js @@ -363,11 +363,6 @@ class Member { this.alias = match[1]; this.overloadIndex = (+match[2]) - 1; } - /** - * Param is true and option false - * @type {Boolean | null} - */ - this.paramOrOption = null; } index() { @@ -384,10 +379,8 @@ class Member { for (const arg of this.argsArray) { this.args.set(arg.name, arg); arg.enclosingMethod = this; - if (arg.name === 'options') { - // @ts-ignore - arg.type.properties.sort((p1, p2) => p1.name.localeCompare(p2.name)); - } + if (arg.name === 'options') + arg.type?.properties?.sort((p1, p2) => p1.name.localeCompare(p2.name)); indexArg(arg); } } @@ -410,11 +403,9 @@ class Member { continue; const overriddenArg = (arg.langs.overrides && arg.langs.overrides[lang]) || arg; overriddenArg.filterForLanguage(lang, options); - // @ts-ignore - if (overriddenArg.name === 'options' && !overriddenArg.type.properties.length) + if (overriddenArg.name === 'options' && !overriddenArg.type?.properties?.length) continue; - // @ts-ignore - overriddenArg.type.filterForLanguage(lang, options); + overriddenArg.type?.filterForLanguage(lang, options); argsArray.push(overriddenArg); } this.argsArray = argsArray; @@ -433,7 +424,6 @@ class Member { const result = new Member(this.kind, { langs: this.langs, since: this.since, deprecated: this.deprecated, discouraged: this.discouraged }, this.name, this.type?.clone(), this.argsArray.map(arg => arg.clone()), this.spec, this.required); result.alias = this.alias; result.async = this.async; - result.paramOrOption = this.paramOrOption; return result; } @@ -526,8 +516,7 @@ class Type { if (!inUnion && (parsedType.union || parsedType.unionName)) { const type = new Type(parsedType.unionName || ''); type.union = []; - // @ts-ignore - for (let t = parsedType; t; t = t.union) { + for (let /** @type {ParsedType | null} */ t = parsedType; t; t = t.union) { const nestedUnion = !!t.unionName && t !== parsedType; type.union.push(Type.fromParsedType(t, !nestedUnion)); if (nestedUnion) @@ -539,7 +528,6 @@ class Type { if (parsedType.args || parsedType.retType) { const type = new Type('function'); type.args = []; - // @ts-ignore for (let t = parsedType.args; t; t = t.next) type.args.push(Type.fromParsedType(t)); type.returnType = parsedType.retType ? Type.fromParsedType(parsedType.retType) : undefined; @@ -549,8 +537,7 @@ class Type { if (parsedType.template) { const type = new Type(parsedType.name); type.templates = []; - // @ts-ignore - for (let t = parsedType.template; t; t = t.next) + for (let /** @type {ParsedType | null} */ t = parsedType.template; t; t = t.next) type.templates.push(Type.fromParsedType(t)); return type; } @@ -613,17 +600,6 @@ class Type { return []; } - /** - * @returns {Member[] | undefined} - */ - sortedProperties() { - if (!this.properties) - return this.properties; - const sortedProperties = [...this.properties]; - sortedProperties.sort((p1, p2) => p1.name.localeCompare(p2.name)); - return sortedProperties; - } - /** * @param {string} lang * @param {LanguageOptions=} options @@ -768,11 +744,10 @@ function patchLinksInText(classOrMember, text, classesMap, membersMap, linkRende let alias = p2; if (classOrMember) { // param/option reference can only be in method or same method parameter comments. - // @ts-ignore - const method = classOrMember.enclosingMethod; - const param = method.argsArray.find(a => a.name === p2); + const method = /** @type {Member} */(classOrMember).enclosingMethod; + const param = method?.argsArray.find(a => a.name === p2); if (!param) - throw new Error(`Referenced parameter ${match} not found in the parent method ${method.name} `); + throw new Error(`Referenced parameter ${match} not found in the parent method ${method?.name} `); alias = param.alias; } return linkRenderer({ param: alias, href }) || match; diff --git a/src/generate.js b/src/generate.js index b3bf36d1565..d2e3d98efa6 100644 --- a/src/generate.js +++ b/src/generate.js @@ -28,6 +28,7 @@ const { CSharpFormatter } = require('./format_csharp'); const isWatch = process.argv.includes('--watch'); const watchProject = process.argv[3]; +const forcedVersion = process.argv.find(arg => arg.startsWith('--version='))?.substring('--version='.length); const srcDir = path.join(process.env.SRC_DIR || '../playwright', 'docs', 'src'); @@ -77,14 +78,19 @@ const versionCache = new Map(); * @returns {Promise} */ async function getVersionForLanguageBindingCached(lang) { + if (forcedVersion) + return forcedVersion; if (!versionCache.has(lang)) { + process.stdout.write(`retrieving package version for ${lang}...`); const version = await getVersionForLanguageBinding(lang); + process.stdout.write(`done\n`); versionCache.set(lang, version); } return versionCache.get(lang); } async function generateDocsForLanguages () { + process.stdout.write(`generating docs for js...`); new Generator({ lang: 'js', version: await getVersionForLanguageBindingCached('js'), @@ -92,6 +98,9 @@ async function generateDocsForLanguages () { outDir: path.join(__dirname, '..', 'nodejs', 'docs'), formatter: new JavaScriptFormatter(), }); + process.stdout.write(`done\n`); + + process.stdout.write(`generating docs for python...`); new Generator({ lang: 'python', version: await getVersionForLanguageBindingCached('python'), @@ -100,6 +109,9 @@ async function generateDocsForLanguages () { formatter: new PythonFormatter(), renderSyncNoArgsMethodAsProperty: true, }); + process.stdout.write(`done\n`); + + process.stdout.write(`generating docs for java...`); new Generator({ lang: 'java', version: await getVersionForLanguageBindingCached('java'), @@ -107,6 +119,9 @@ async function generateDocsForLanguages () { outDir: path.join(__dirname, '..', 'java', 'docs'), formatter: new JavaFormatter(), }); + process.stdout.write(`done\n`); + + process.stdout.write(`generating docs for csharp...`); new Generator({ lang: 'csharp', version: await getVersionForLanguageBindingCached('csharp'), @@ -114,13 +129,14 @@ async function generateDocsForLanguages () { outDir: path.join(__dirname, '..', 'dotnet', 'docs'), formatter: new CSharpFormatter(), }); + process.stdout.write(`done\n`); }; /** - * @param {'add'|'addDir'|'change'|'unlink'|'unlinkDir'} event - * @param {string} from + * @param {'add'|'addDir'|'change'|'unlink'|'unlinkDir'} event + * @param {string} from */ -async function syncWithWorkingDirectory (event, from) { +async function syncWithWorkingDirectory(event, from) { const to = path.join(path.join(__dirname, '..', path.relative(path.join(__dirname, '..', lang2Folder[watchProject]), from))); switch (event) { case 'addDir': @@ -163,6 +179,7 @@ async function syncWithWorkingDirectory (event, from) { }); async function updateStarsButton() { + process.stdout.write(`updating "stars" button...`); const kMagicComment = '// NOTE: this line is generated by src/generate.js. Do not change!'; const kGitHubStarsButtonSource = path.join(__dirname, 'components/GitHubStarButton/index.tsx'); const repoInfoResponse = await new Promise((resolve, reject) => { @@ -189,4 +206,5 @@ async function updateStarsButton() { const starLineIndex = lines.findIndex(line => line.includes(kMagicComment)); lines[starLineIndex] = `const STARS = '${roundedStarsCount}k+'; ${kMagicComment}`; await fs.promises.writeFile(kGitHubStarsButtonSource, lines.join('\n')); + process.stdout.write(`done\n`); } diff --git a/src/generator.js b/src/generator.js index defe1ce14c2..6bfe6d4cc4a 100644 --- a/src/generator.js +++ b/src/generator.js @@ -719,8 +719,7 @@ function calculatePropertyHash(member, direction) { if (direction === 'out') return `${prefix}-return`; const propertyName = toKebabCase(member.name); - const propertyDescription = member.paramOrOption ? 'param' : 'option'; - return `${prefix}-${propertyDescription}-${propertyName}`.toLowerCase(); + return `${prefix}-option-${propertyName}`.toLowerCase(); } const fileWriteCache = new Map(); diff --git a/src/sync_upstream_scripts.js b/src/sync_upstream_scripts.js index af26adadbc1..176b101e181 100644 --- a/src/sync_upstream_scripts.js +++ b/src/sync_upstream_scripts.js @@ -1,14 +1,13 @@ -const path = require("path") -const fs = require("fs") +const path = require('path'); +const fs = require('fs'); -const srcDir = process.env.SRC_DIR || '../playwright' +const srcDir = process.env.SRC_DIR || '../playwright'; +fs.copyFileSync(path.join(srcDir, 'utils', 'markdown.js'), path.join(__dirname, 'markdown.js')); -fs.copyFileSync(path.join(srcDir, "utils", "markdown.js"), path.join(__dirname, 'markdown.js')) +let documentationJsFile = fs.readFileSync(path.join(srcDir, 'utils', 'doclint', 'documentation.js')).toString(); +documentationJsFile = documentationJsFile.replace(/\.\.\/markdown/g, './markdown'); +fs.writeFileSync(path.join(__dirname, 'documentation.js'), documentationJsFile); -let documentationJsFile = fs.readFileSync(path.join(srcDir, "utils", "doclint", "documentation.js")).toString() -documentationJsFile = documentationJsFile.replace(/\.\.\/markdown/g, './markdown') -fs.writeFileSync(path.join(__dirname, 'documentation.js'), documentationJsFile) - -let apiParserJsFile = fs.readFileSync(path.join(srcDir, "utils", "doclint", "api_parser.js")).toString() -apiParserJsFile = apiParserJsFile.replace(/\.\.\/markdown/g, './markdown') -fs.writeFileSync(path.join(__dirname, 'api_parser.js'), apiParserJsFile) +let apiParserJsFile = fs.readFileSync(path.join(srcDir, 'utils', 'doclint', 'api_parser.js')).toString(); +apiParserJsFile = apiParserJsFile.replace(/\.\.\/markdown/g, './markdown'); +fs.writeFileSync(path.join(__dirname, 'api_parser.js'), apiParserJsFile);