@mintlify/scraping 4.0.1242 → 4.0.1244

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/scraping",
-  "version": "4.0.1242",
+  "version": "4.0.1244",
   "description": "Scrape documentation frameworks to Mintlify docs",
   "engines": {
     "node": ">=18.0.0"
@@ -43,7 +43,7 @@
     "format:check": "oxfmt --check"
   },
   "dependencies": {
-    "@mintlify/common": "1.0.1360",
+    "@mintlify/common": "1.0.1361",
     "fast-xml-parser": "5.7.3",
     "fs-extra": "11.1.1",
     "graphql": "16.11.0",
@@ -62,9 +62,9 @@
     "zod": "3.24.0"
   },
   "devDependencies": {
-    "@mintlify/models": "0.0.392",
+    "@mintlify/models": "0.0.393",
     "@mintlify/ts-config": "2.0.2",
-    "@mintlify/validation": "0.1.970",
+    "@mintlify/validation": "0.1.971",
     "@tsconfig/recommended": "1.0.2",
     "@types/hast": "3.0.4",
     "@types/mdast": "4.0.4",
@@ -87,5 +87,5 @@
       "optional": true
     }
   },
-  "gitHead": "121922c15ff85f7af9ee5f331edbe2e4c2967c17"
+  "gitHead": "3b7270d4371e9e7e3370bc6c7341ffbc82346f59"
 }

package/src/sdk/converters/docfx.ts

@@ -26,10 +26,14 @@ type DocfxItem = {
   remarks?: string;
   example?: string[];
   syntax?: DocfxSyntax;
+  inheritance?: string[];
+  implements?: string[];
 };
 type DocfxFile = { items?: DocfxItem[]; references?: { uid?: string; name?: string }[] };
 type TocNode = { uid?: string; type?: string; items?: TocNode[] };
 
+const ROOT_BASE_TYPES = new Set(['System.Object', 'System.ValueType', 'System.Enum']);
+
 const PAGE_TAGS: Record<string, string> = {
   Class: 'CLASS',
   Interface: 'INTERFACE',
@@ -198,6 +202,7 @@ class DocfxRenderer {
   renderPage(item: DocfxItem): SdkPage {
     const lines: string[] = [this.prose(item.summary)];
     if (item.syntax?.content) lines.push(this.codeBlock(item.syntax.content));
+    lines.push(...this.renderHeritage(item));
     lines.push(this.prose(item.remarks));
     lines.push(...(item.example ?? []).map((example) => this.renderExample(example)));
 
@@ -268,6 +273,24 @@ class DocfxRenderer {
     return lines;
   }
 
+  private renderHeritage(item: DocfxItem): string[] {
+    const parent = item.inheritance?.at(-1);
+    return [
+      {
+        label: 'Extends',
+        uids: parent && !ROOT_BASE_TYPES.has(parent) ? [parent] : [],
+      },
+      { label: 'Implements', uids: item.implements ?? [] },
+    ]
+      .filter(({ uids }) => uids.length)
+      .map(
+        ({ label, uids }) =>
+          `**${label}:** ${uids
+            .map((uid) => linkedCode(this.typeTokens(uid)) ?? inlineCode(this.typeName(uid)))
+            .join(', ')}`
+      );
+  }
+
   private renderEnum(item: DocfxItem): string[] {
     const lines: string[] = ['## Members'];
     for (const member of this.members(item).filter((child) => child.type === 'Field')) {

package/src/sdk/converters/phpdoc.ts

@@ -286,15 +286,21 @@ class PhpdocRenderer {
   private renderHeritage(entry: Entry): string[] {
     const { element } = entry;
     const heritage = [
-      element.extends ? `extends ${element.extends}` : '',
-      element.implements?.length ? `implements ${element.implements.join(', ')}` : '',
-    ].filter(Boolean);
+      { label: 'Extends', types: element.extends ? [element.extends] : [] },
+      { label: 'Implements', types: element.implements ?? [] },
+    ].filter(({ types }) => types.length);
     if (!heritage.length) return [];
     const modifiers = [
       element['@_abstract'] === 'true' ? 'abstract' : '',
       element['@_final'] === 'true' ? 'final' : '',
     ].filter(Boolean);
-    return [this.codeBlock([...modifiers, entry.keyword, entry.name, ...heritage].join(' '))];
+    return [
+      this.codeBlock([...modifiers, entry.keyword, entry.name].join(' ')),
+      ...heritage.map(
+        ({ label, types }) =>
+          `**${label}:** ${types.map((type) => linkedCode(this.typeTokens(type)) ?? inlineCode(type)).join(', ')}`
+      ),
+    ];
   }
 
   private renderMethodBody(method: PhpMethod, depth: number): string[] {

package/src/sdk/converters/typedoc.ts

@@ -1,3 +1,4 @@
+import { cachedSlugify, slugify as headingSlug } from '@mintlify/common';
 import type { SdkSymbolKind } from '@mintlify/models';
 import fse from 'fs-extra';
 import path from 'node:path';
@@ -120,6 +121,16 @@ const SECTIONS: {
 const MAX_PLACEMENTS_PER_PAGE = 8;
 const MAX_DECLARATION_NAME_LENGTH = 512;
 
+const FIELD_MEMBER_KINDS = new Set<number>([KIND.property, KIND.accessor]);
+
+function memberAnchor(member: TypedocNode, inEnum: boolean): string | undefined {
+  if (inEnum || FIELD_MEMBER_KINDS.has(member.kind)) {
+    return cachedSlugify(`${inEnum ? 'member' : 'property'}-${member.name}`, { decamelize: true });
+  }
+  if (member.kind === KIND.method) return headingSlug(`${member.name}()`);
+  return undefined;
+}
+
 const MEMBER_KINDS = new Set<number>([KIND.constructor, KIND.property, KIND.accessor, KIND.method]);
 
 const DEFAULT_GROUP_TITLE_BY_KIND = new Map<number, string>([
@@ -164,7 +175,20 @@ export async function convertTypedoc(sourcePath: string): Promise<SdkReference>
     }
   }
 
-  const renderer = new TypedocRenderer(slugById);
+  const memberSlugById = new Map<number, string>();
+  for (const module of modules) {
+    for (const { node } of collectDeclarations(module)) {
+      const slug = slugById.get(node.id);
+      if (!slug) continue;
+      for (const child of node.children ?? []) {
+        if (child.flags?.isPrivate) continue;
+        const anchor = memberAnchor(child, node.kind === KIND.enum);
+        if (anchor) memberSlugById.set(child.id, `${slug}#${anchor}`);
+      }
+    }
+  }
+
+  const renderer = new TypedocRenderer(slugById, memberSlugById);
   const pages: SdkPage[] = [];
   const groups: SdkNavGroup[] = [];
   const moduleGroupById = new Map<number, PathNavGroup>();
@@ -353,7 +377,10 @@ function slugify(name: string): string {
 }
 
 class TypedocRenderer {
-  constructor(private slugById: Map<number, string>) {}
+  constructor(
+    private slugById: Map<number, string>,
+    private memberSlugById = new Map<number, string>()
+  ) {}
 
   renderOverview(node: TypedocNode, slug: string, pages: SdkPage[], namespace?: string): SdkPage {
     const tree = parseSdkReadme(this.partsMarkdown(node.readme ?? []));
@@ -461,22 +488,15 @@ class TypedocRenderer {
   }
 
   private renderClassLike(node: TypedocNode): string[] {
-    const lines: string[] = [];
-    const heritage = [
-      ...(node.extendedTypes?.length
-        ? [`extends ${node.extendedTypes.map((t) => this.type(t)).join(', ')}`]
-        : []),
-      ...(node.implementedTypes?.length
-        ? [`implements ${node.implementedTypes.map((t) => this.type(t)).join(', ')}`]
-        : []),
-    ];
-    if (heritage.length) {
-      lines.push(
-        this.codeBlock(
-          `${node.kind === KIND.class ? 'class' : 'interface'} ${node.name} ${heritage.join(' ')}`
-        )
+    const lines = [
+      { label: 'Extends', types: node.extendedTypes },
+      { label: 'Implements', types: node.implementedTypes },
+    ]
+      .filter(({ types }) => types?.length)
+      .map(
+        ({ label, types }) =>
+          `**${label}:** ${(types ?? []).map((type) => this.linkedOrCode(type)).join(', ')}`
       );
-    }
 
     const members = (node.children ?? []).filter((child) => !child.flags?.isPrivate);
     const layout = this.memberLayout(node, members);
@@ -559,7 +579,8 @@ class TypedocRenderer {
           property.name,
           type,
           property.flags?.isOptional === true,
-          this.comment(property.comment ?? property.getSignature?.comment)
+          this.comment(property.comment ?? property.getSignature?.comment),
+          memberAnchor(property, false)
         )
       );
     }
@@ -578,7 +599,9 @@ class TypedocRenderer {
           member.name,
           member.type?.type === 'literal' ? JSON.stringify(member.type.value) : '',
           false,
-          this.comment(member.comment)
+          this.comment(member.comment),
+          undefined,
+          memberAnchor(member, true)
         )
       );
     }
@@ -586,15 +609,11 @@ class TypedocRenderer {
   }
 
   private renderSignatures(node: TypedocNode, depth: number): string[] {
+    const signatures = node.signatures ?? [];
+    if (signatures.length > 1) return this.renderOverloads(signatures, depth);
     const lines: string[] = [];
-    for (const signature of node.signatures ?? []) {
-      const params = (signature.parameters ?? [])
-        .map(
-          (param) =>
-            `${param.name}${param.flags?.isOptional || param.defaultValue !== undefined ? '?' : ''}: ${this.type(param.type)}`
-        )
-        .join(', ');
-      lines.push(this.codeBlock(`${signature.name}(${params}): ${this.type(signature.type)}`));
+    for (const signature of signatures) {
+      lines.push(this.codeBlock(this.signatureLine(signature)));
       const comment = this.comment(signature.comment);
       if (comment) lines.push(comment);
       if (signature.parameters?.length) {
@@ -621,18 +640,91 @@ class TypedocRenderer {
     return lines;
   }
 
+  private renderOverloads(signatures: TypedocNode[], depth: number): string[] {
+    const lines = [
+      this.codeBlock(signatures.map((signature) => this.signatureLine(signature)).join('\n')),
+      ...distinct(signatures.map((signature) => this.comment(signature.comment))),
+    ];
+
+    const names = distinct(
+      signatures.flatMap((signature) => (signature.parameters ?? []).map((param) => param.name))
+    );
+    if (names.length) lines.push(detailHeading('Parameters', depth));
+    for (const name of names) {
+      const params = signatures.map((signature) =>
+        signature.parameters?.find((param) => param.name === name)
+      );
+      const present = params.filter((param) => param !== undefined);
+      const optional = params.some(
+        (param) => !param || param.flags?.isOptional === true || param.defaultValue !== undefined
+      );
+      const body = distinct(present.map((param) => this.comment(param.comment))).join('\n\n');
+      const types = this.distinctTypes(present.map((param) => param.type));
+      const [only] = types;
+      if (types.length === 1) {
+        lines.push(this.typeField(name, only, optional, body));
+        continue;
+      }
+      const variants = types.map((type) => `- ${this.linkedOrCode(type)}`).join('\n');
+      lines.push(
+        responseField(
+          name,
+          types.map((type) => this.type(type)).join(' | '),
+          optional,
+          [`**Type:** one of\n\n${variants}`, body].filter(Boolean).join('\n\n')
+        )
+      );
+    }
+
+    const returnTypes = this.distinctTypes(signatures.map((signature) => signature.type)).filter(
+      (type) => this.type(type) !== 'void'
+    );
+    if (returnTypes.length) {
+      lines.push(
+        detailHeading('Returns', depth),
+        returnTypes.map((type) => this.linkedOrCode(type)).join(' | '),
+        ...distinct(
+          signatures.map((signature) => {
+            const returns = signature.comment?.blockTags?.find((tag) => tag.tag === '@returns');
+            return returns ? this.parts(returns.content) : '';
+          })
+        )
+      );
+    }
+    return lines;
+  }
+
+  private distinctTypes(types: (TypedocType | undefined)[]): (TypedocType | undefined)[] {
+    return [...new Map(types.map((type) => [this.linkedOrCode(type), type])).values()];
+  }
+
+  private signatureLine(signature: TypedocNode): string {
+    const params = (signature.parameters ?? [])
+      .map(
+        (param) =>
+          `${param.name}${param.flags?.isOptional || param.defaultValue !== undefined ? '?' : ''}: ${this.type(param.type)}`
+      )
+      .join(', ');
+    return `${signature.name}(${params}): ${this.type(signature.type)}`;
+  }
+
+  private linkedOrCode(type?: TypedocType): string {
+    return this.linkedType(type) ?? inlineCode(this.type(type));
+  }
+
   private typeField(
     name: string,
     type: TypedocType | undefined,
     optional: boolean,
-    body?: string
+    body?: string,
+    id?: string
   ): string {
     const tokens = this.typeTokens(type);
     const [only] = tokens;
     const typeHref = tokens.length === 1 && only?.href ? `/${only.href}` : undefined;
     const linked = typeHref ? undefined : this.linkedType(type);
     const content = [linked && `**Type:** ${linked}`, body].filter(Boolean).join('\n\n');
-    return responseField(name, this.type(type), optional, content, typeHref);
+    return responseField(name, this.type(type), optional, content, typeHref, id);
   }
 
   private codeBlock(code: string): string {
@@ -661,9 +753,11 @@ class TypedocRenderer {
     return parts
       .map((part) => {
         if (part.kind === 'inline-tag') {
-          if (typeof part.target === 'number' && this.slugById.has(part.target)) {
-            return `[${part.text}](/${this.slugById.get(part.target)})`;
-          }
+          const slug =
+            typeof part.target === 'number'
+              ? (this.slugById.get(part.target) ?? this.memberSlugById.get(part.target))
+              : undefined;
+          if (slug) return `[${part.text}](/${slug})`;
           if (typeof part.target === 'string') return `[${part.text}](${part.target})`;
           return `\`${part.text}\``;
         }
@@ -790,3 +884,7 @@ function headingText(title: unknown): string {
 function detailHeading(title: string, depth: number): string {
   return depth <= MAX_HEADING_DEPTH ? `${'#'.repeat(depth)} ${title}` : `**${title}**`;
 }
+
+function distinct(items: string[]): string[] {
+  return [...new Set(items)].filter(Boolean);
+}