Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: validate links for all languages (#8478)

Browse source
This commit is contained in:
Dmitry Gozman 2021-08-26 10:59:33 -07:00 committed by GitHub
parent 96fde46f27
commit 17146b44c2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 58 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
utils/doclint/cli.js
View file

@ -37,18 +37,6 @@ run().catch(e => {
});; });;
async function run() { async function run() {
const apiDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
apiDocumentation.filterForLanguage('js');
const testDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'test-api'), path.join(PROJECT_DIR, 'docs', 'src', 'api', 'params.md'));
testDocumentation.filterForLanguage('js');
const testRerpoterDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'test-reporter-api'));
testRerpoterDocumentation.filterForLanguage('js');
const documentation = apiDocumentation.mergeWith(testDocumentation).mergeWith(testRerpoterDocumentation);
documentation.mergeWith(testDocumentation);
// This validates member links.
documentation.setLinkRenderer(() => undefined);
// Patch README.md // Patch README.md
const versions = await getBrowserVersions(); const versions = await getBrowserVersions();
{ {
@ -108,16 +96,41 @@ async function run() {
// Validate links // Validate links
{ {
for (const file of fs.readdirSync(path.join(PROJECT_DIR, 'docs', 'src'))) { const langs = ['js', 'java', 'python', 'csharp'];
if (!file.endsWith('.md')) for (const lang of langs) {
continue; try {
const data = fs.readFileSync(path.join(PROJECT_DIR, 'docs', 'src', file)).toString(); let documentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
documentation.renderLinksInText(md.parse(data)); documentation.filterForLanguage(lang);
if (lang === 'js') {
const testDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'test-api'), path.join(PROJECT_DIR, 'docs', 'src', 'api', 'params.md'));
testDocumentation.filterForLanguage('js');
const testRerpoterDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'test-reporter-api'));
testRerpoterDocumentation.filterForLanguage('js');
documentation = documentation.mergeWith(testDocumentation).mergeWith(testRerpoterDocumentation);
}
// This validates member links.
documentation.setLinkRenderer(() => undefined);
for (const file of fs.readdirSync(path.join(PROJECT_DIR, 'docs', 'src'))) {
if (!file.endsWith('.md'))
continue;
if (langs.some(other => other !== lang && file.endsWith(`-${other}.md`)))
continue;
const data = fs.readFileSync(path.join(PROJECT_DIR, 'docs', 'src', file)).toString();
documentation.renderLinksInText(md.filterNodesForLanguage(md.parse(data), lang));
}
} catch (e) {
e.message = `While processing "${lang}"\n` + e.message;
throw e;
}
} }
} }
// Check for missing docs // Check for missing docs
{ {
const apiDocumentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
apiDocumentation.filterForLanguage('js');
const srcClient = path.join(PROJECT_DIR, 'src', 'client'); const srcClient = path.join(PROJECT_DIR, 'src', 'client');
const sources = fs.readdirSync(srcClient).map(n => path.join(srcClient, n)); const sources = fs.readdirSync(srcClient).map(n => path.join(srcClient, n));
const errors = missingDocs(apiDocumentation, sources, path.join(srcClient, 'api.ts')); const errors = missingDocs(apiDocumentation, sources, path.join(srcClient, 'api.ts'));

29
utils/markdown.js
View file

@ -386,4 +386,31 @@ function generateToc(nodes, h3) {
return result.join('\n'); return result.join('\n');
} }
module.exports = { parse, render, clone, visitAll, visit, generateToc }; /**
* @param {MarkdownNode[]} nodes
* @param {string} language
* @return {MarkdownNode[]}
*/
function filterNodesForLanguage(nodes, language) {
const result = nodes.filter(node => {
if (!node.children)
return true;
for (let i = 0; i < node.children.length; i++) {
const child = node.children[i];
if (child.type !== 'li' || child.liType !== 'bullet' || !child.text.startsWith('langs:'))
continue;
const only = child.text.substring('langs:'.length).split(',').map(l => l.trim());
node.children.splice(i, 1);
return only.includes(language);
}
return true;
});
result.forEach(n => {
if (!n.children)
return;
n.children = filterNodesForLanguage(n.children, language);
});
return result;
}
module.exports = { parse, render, clone, visitAll, visit, generateToc, filterNodesForLanguage };