Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore: roll documentation scripts #1530

Merged
merged 1 commit into from
Sep 24, 2024
Merged

chore: roll documentation scripts #1530

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 9 additions & 34 deletions src/documentation.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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);
}
}
Expand All @@ -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;
Expand All @@ -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;
}

Expand Down Expand Up @@ -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)
Expand All @@ -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;
Expand All @@ -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;
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand Down
24 changes: 21 additions & 3 deletions src/generate.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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');

Expand Down Expand Up @@ -77,21 +78,29 @@ const versionCache = new Map();
* @returns {Promise<string>}
*/
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'),
srcDir,
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'),
Expand All @@ -100,27 +109,34 @@ 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'),
srcDir,
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'),
srcDir,
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':
Expand Down Expand Up @@ -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) => {
Expand All @@ -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`);
}
3 changes: 1 addition & 2 deletions src/generator.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
21 changes: 10 additions & 11 deletions src/sync_upstream_scripts.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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);