Note
Errors that are just general programming errors, such as incorrect typing, may still raise
diff --git a/scripts/lib/api/processHtml.ts b/scripts/lib/api/processHtml.ts
index c5e41c7e36f..8daa34709ec 100644
--- a/scripts/lib/api/processHtml.ts
+++ b/scripts/lib/api/processHtml.ts
@@ -10,12 +10,11 @@
// copyright notice, and modified files need to carry a notice indicating
// that they have been altered from the originals.
-import { CheerioAPI, Cheerio, load } from "cheerio";
+import { CheerioAPI, Cheerio, load, Element } from "cheerio";
import { Image } from "./HtmlToMdResult";
import { Metadata, ApiType } from "./Metadata";
-import { getLastPartFromFullIdentifier } from "../stringUtils";
-import { findByText, prepareGitHubLink } from "./generateApiComponents";
+import { processMdxComponent } from "./generateApiComponents";
export type ProcessedHtml = {
html: string;
@@ -24,13 +23,13 @@ export type ProcessedHtml = {
isReleaseNotes: boolean;
};
-export function processHtml(options: {
+export async function processHtml(options: {
html: string;
fileName: string;
imageDestination: string;
determineGithubUrl: (fileName: string) => string;
releaseNotesTitle: string;
-}): ProcessedHtml {
+}): Promise {
const {
html,
fileName,
@@ -61,7 +60,7 @@ export function processHtml(options: {
preserveMathBlockWhitespace($, $main);
const meta: Metadata = {};
- processMembersAndSetMeta($, $main, meta);
+ await processMembersAndSetMeta($, $main, meta);
maybeSetModuleMetadata($, $main, meta);
if (meta.apiType === "module") {
updateModuleHeadings($, $main, meta);
@@ -260,11 +259,11 @@ export function removeColonSpans($main: Cheerio): void {
$main.find(".colon").remove();
}
-export function processMembersAndSetMeta(
+export async function processMembersAndSetMeta(
$: CheerioAPI,
$main: Cheerio,
meta: Metadata,
-): void {
+): Promise {
let continueMapMembers = true;
while (continueMapMembers) {
// members can be recursive, so we need to pick elements one by one
@@ -283,173 +282,41 @@ export function processMembersAndSetMeta(
const id = $dl.find("dt").attr("id") || "";
const apiType = getApiType($dl);
- const replacement = $dl
- .children()
- .toArray()
- .map((child) => {
- const $child = $(child);
- if (child.name !== "dt" || !apiType) {
- return `${$child.html()}
`;
- }
-
- const priorApiType = meta.apiType;
- if (!priorApiType) {
- meta.apiType = apiType;
- meta.apiName = id;
- }
-
- return processMember($, $main, $child, $dl, priorApiType, apiType, id);
- })
- .join("\n");
-
- $dl.replaceWith(`${replacement}
`);
- }
-}
-
-function processMember(
- $: CheerioAPI,
- $main: Cheerio,
- $child: Cheerio,
- $dl: Cheerio,
- priorApiType: string | undefined,
- apiType: string,
- id: string,
-) {
- const githubUrl = prepareGitHubLink($child, apiType === "method");
- const githubSourceLink = githubUrl
- ? ` GitHub`
- : "";
-
- findByText($, $main, "em.property", apiType).remove();
-
- if (apiType == "class") {
- return `${$child.html()}${githubSourceLink}
`;
- }
-
- if (apiType == "property") {
- return processProperty($child, $dl, priorApiType, id, githubSourceLink);
- }
-
- if (apiType == "method") {
- return processMethod($, $child, $dl, priorApiType, id, githubSourceLink);
- }
-
- if (apiType == "attribute") {
- return processAttribute($child, $dl, priorApiType, id, githubSourceLink);
- }
-
- if (apiType === "function" || apiType === "exception") {
- return processFunctionOrException($child, $dl, id, githubSourceLink);
- }
-
- throw new Error(`Unhandled Python type: ${apiType}`);
-}
-
-function processProperty(
- $child: Cheerio,
- $dl: Cheerio,
- priorApiType: string | undefined,
- id: string,
- githubSourceLink: string,
-) {
- if (!priorApiType && id) {
- $dl.siblings("h1").text(getLastPartFromFullIdentifier(id));
- }
-
- const signature = $child.find("em").text()?.replace(/^:\s+/, "");
- if (signature.trim().length === 0) return;
- return `${signature}${githubSourceLink}
`;
-}
-
-function processMethod(
- $: CheerioAPI,
- $child: Cheerio,
- $dl: Cheerio,
- priorApiType: string | undefined,
- id: string,
- githubSourceLink: string,
-) {
- if (id) {
+ const priorApiType = meta.apiType;
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);
+ meta.apiType = apiType;
+ meta.apiName = id;
}
- }
- return `${$child.html()}${githubSourceLink}
`;
-}
+ const bodyElements: string[] = [];
+ const signatures: Cheerio[] = [];
-function processAttribute(
- $child: Cheerio,
- $dl: Cheerio,
- priorApiType: string | undefined,
- id: string,
- githubSourceLink: string,
-) {
- if (!priorApiType) {
- if (id) {
- $dl.siblings("h1").text(getLastPartFromFullIdentifier(id));
+ for (const child of $dl.children().toArray()) {
+ const $child = $(child);
+ if (child.name !== "dt" || !apiType) {
+ bodyElements.push(`${$child.html()}
`);
+ continue;
+ }
+ signatures.push($child);
}
- 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;
+ if (signatures.length == 0) {
+ $dl.replaceWith(`${bodyElements.join("\n")}
`);
+ } else {
+ const [openTag, closeTag] = await processMdxComponent(
+ $,
+ $main,
+ signatures,
+ $dl,
+ priorApiType,
+ apiType!,
+ id,
+ );
+ $dl.replaceWith(
+ `${openTag}\n${bodyElements.join("\n")}\n${closeTag}
`,
+ );
+ }
}
-
- const apiName = id.split(".").slice(-1)[0];
- return `${apiName}
${descriptionHtml}`;
}
export function maybeSetModuleMetadata(