diff --git a/scripts/lib/api/processHtml.ts b/scripts/lib/api/processHtml.ts index c7d4dea34a3..f4292c35147 100644 --- a/scripts/lib/api/processHtml.ts +++ b/scripts/lib/api/processHtml.ts @@ -279,127 +279,185 @@ export function processMembersAndSetMeta( } const $dl = $(dl); + const id = $dl.find("dt").attr("id") || ""; + const apiType = getApiType($dl); + const priorApiType = meta.apiType; + + if (!priorApiType) { + meta.apiType = apiType; + meta.apiName = id; + } + const replacement = $dl .children() .toArray() .map((child) => { const $child = $(child); - const id = $dl.find("dt").attr("id") || ""; - const apiType = getApiType($dl); - - const github = prepareGitHubLink($child, apiType === "method"); + const githubSourceLink = prepareGitHubLink( + $child, + apiType === "method", + ); if (child.name !== "dt" || !apiType) { return `
${$child.html()}
`; } + return processMember( + $, + $main, + $child, + $dl, + priorApiType, + apiType, + id, + githubSourceLink, + ); + }) + .join("\n"); - const priorApiType = meta.apiType; - if (!priorApiType) { - meta.apiType = apiType; - meta.apiName = id; - } + $dl.replaceWith(`
${replacement}
`); + } +} - if (apiType == "class") { - findByText($, $main, "em.property", "class").remove(); - return `

${$child.html()}${github}

`; - } +function processMember( + $: CheerioAPI, + $main: Cheerio, + $child: Cheerio, + $dl: Cheerio, + priorApiType: string | undefined, + apiType: string, + id: string, + githubSourceLink: string, +) { + findByText($, $main, "em.property", apiType).remove(); + + if (apiType == "class") { + return `

${$child.html()}${githubSourceLink}

`; + } - if (apiType == "property") { - if (!priorApiType && id) { - $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); - } + if (apiType == "property") { + return processProperty($child, $dl, priorApiType, id, githubSourceLink); + } - findByText($, $main, "em.property", "property").remove(); - const signature = $child.find("em").text()?.replace(/^:\s+/, ""); - if (signature.trim().length === 0) return; - return `

${signature}${github}

`; - } + if (apiType == "method") { + return processMethod($, $child, $dl, priorApiType, id, githubSourceLink); + } - if (apiType == "method") { - if (id) { - if (!priorApiType) { - $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); - } else if (!$child.attr("id")) { - // Overload methods have more than one
tag, but only the first one - // contains an id. - return `

${$child.html()}${github}

`; - } else { - // Inline methods - $(`

${getLastPartFromFullIdentifier(id)}

`).insertBefore( - $dl, - ); - } - } - - findByText($, $main, "em.property", "method").remove(); - return `

${$child.html()}${github}

`; - } + if (apiType == "attribute") { + return processAttribute($child, $dl, priorApiType, id, githubSourceLink); + } - if (apiType == "attribute") { - if (!priorApiType) { - if (id) { - $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); - } - - findByText($, $main, "em.property", "attribute").remove(); - const signature = $child.find("em").text()?.replace(/^:\s+/, ""); - if (signature.trim().length === 0) return; - return `

${signature}${github}

`; - } - - // Else, the attribute is embedded on the class - const text = $child.text(); - - // Index of the default value of the attribute - const equalIndex = text.indexOf("="); - // Index of the attribute's type. The type should be - // found before the default value - const colonIndex = text.slice(0, equalIndex).indexOf(":"); - - let name = text; - let type: string | undefined; - let value: string | undefined; - if (colonIndex > 0 && equalIndex > 0) { - name = text.substring(0, colonIndex); - type = text.substring(colonIndex + 1, equalIndex); - value = text.substring(equalIndex); - } else if (colonIndex > 0) { - name = text.substring(0, colonIndex); - type = text.substring(colonIndex + 1); - } else if (equalIndex > 0) { - name = text.substring(0, equalIndex); - value = text.substring(equalIndex); - } - const output = [`

${name}

`]; - if (type) { - output.push(`

${type}

`); - } - if (value) { - output.push(`

${value}

`); - } - return output.join("\n"); - } + if (apiType === "function" || apiType === "exception") { + return processFunctionOrException($child, $dl, id, githubSourceLink); + } - if (apiType === "function" || apiType === "exception") { - findByText($, $main, "em.property", apiType).remove(); - const descriptionHtml = `

${$child.html()}${github}

`; + throw new Error(`Unhandled Python type: ${apiType}`); +} - const pageHeading = $dl.siblings("h1").text(); - if (id.endsWith(pageHeading) && pageHeading != "") { - // Page is already dedicated to apiType; no heading needed - return descriptionHtml; - } +function processProperty( + $child: Cheerio, + $dl: Cheerio, + priorApiType: string | undefined, + id: string, + githubSourceLink: string, +) { + if (!priorApiType && id) { + $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); + } - const apiName = id.split(".").slice(-1)[0]; - return `

${apiName}

${descriptionHtml}`; - } + const signature = $child.find("em").text()?.replace(/^:\s+/, ""); + if (signature.trim().length === 0) return; + return `

${signature}${githubSourceLink}

`; +} - throw new Error(`Unhandled Python type: ${apiType}`); - }) - .join("\n"); +function processMethod( + $: CheerioAPI, + $child: Cheerio, + $dl: Cheerio, + priorApiType: string | undefined, + id: string, + githubSourceLink: string, +) { + if (id) { + if (!priorApiType) { + $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); + } else if (!$child.attr("id")) { + // Overload methods have more than one
tag, but only the first one + // contains an id. + return `

${$child.html()}${githubSourceLink}

`; + } else { + // Inline methods + $(`

${getLastPartFromFullIdentifier(id)}

`).insertBefore($dl); + } + } - $dl.replaceWith(`
${replacement}
`); + return `

${$child.html()}${githubSourceLink}

`; +} + +function processAttribute( + $child: Cheerio, + $dl: Cheerio, + priorApiType: string | undefined, + id: string, + githubSourceLink: string, +) { + if (!priorApiType) { + if (id) { + $dl.siblings("h1").text(getLastPartFromFullIdentifier(id)); + } + + const signature = $child.find("em").text()?.replace(/^:\s+/, ""); + if (signature.trim().length === 0) return; + return `

${signature}${githubSourceLink}

`; } + + // Else, the attribute is embedded on the class + const text = $child.text(); + + // Index of the default value of the attribute + let equalIndex = text.indexOf("="); + if (equalIndex == -1) { + equalIndex = text.length; + } + // Index of the attribute's type. The type should be + // found before the default value + let colonIndex = text.slice(0, equalIndex).indexOf(":"); + if (colonIndex == -1) { + colonIndex = text.length; + } + + // The attributes have the following shape: name [: type] [= value] + const name = text.slice(0, Math.min(colonIndex, equalIndex)).trim(); + const type = text + .slice(Math.min(colonIndex + 1, equalIndex), equalIndex) + .trim(); + const value = text.slice(equalIndex, text.length).trim(); + + const output = [`

${name}

`]; + if (type) { + output.push(`

${type}

`); + } + if (value) { + output.push(`

${value}

`); + } + return output.join("\n"); +} + +function processFunctionOrException( + $child: Cheerio, + $dl: Cheerio, + id: string, + githubSourceLink: string, +) { + const descriptionHtml = `

${$child.html()}${githubSourceLink}

`; + + const pageHeading = $dl.siblings("h1").text(); + if (id.endsWith(pageHeading) && pageHeading != "") { + // Page is already dedicated to apiType; no heading needed + return descriptionHtml; + } + + const apiName = id.split(".").slice(-1)[0]; + return `

${apiName}

${descriptionHtml}`; } /**