@apify/docusaurus-plugin-typedoc-api 4.4.12 → 5.1.0

package/lib/plugin/python/transformation.js

@@ -1,414 +1,447 @@
-'use strict';
-
-function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
-function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
-function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
-function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-const consts = require('./consts.js');
-const inheritance = require('./inheritance.js');
-const index = require('./type-parsing/index.js');
-const utils = require('./utils.js');
-
 /* eslint-disable max-classes-per-file */
-class SymbolIdTracker {
-  symbolIdMap = {};
-  idToReference = {};
-  oidGenerator = this.generateOID();
-
-  /**
-   * Returns automatically incrementing OID. Every call to this function will return a new unique OID.
-   * @returns {number} The OID.
-   */
-  getNewId() {
-    return this.oidGenerator.next().value;
-  }
-  addNewReference(object) {
-    if (object.sources?.[0]?.fileName) {
-      this.symbolIdMap[object.id] = {
-        qualifiedName: object.name,
-        sourceFileName: object.sources?.[0]?.fileName
-      };
+import { REPO_ROOT_PLACEHOLDER, TYPEDOC_KINDS } from './consts';
+import { InheritanceGraph } from './inheritance';
+import { PythonTypeResolver } from './type-parsing';
+import { getGroupName, isHidden, isOverload, projectUsesDocsGroupDecorator, sortChildren } from './utils';
+export class SymbolIdTracker {
+    constructor() {
+        this.symbolIdMap = {};
+        this.idToReference = {};
+        this.oidGenerator = this.generateOID();
     }
-    this.idToReference[object.id] = object;
-  }
-  getMethodSignatures() {
-    return Object.values(this.idToReference).filter(({
-      kindString
-    }) => kindString === 'Call signature');
-  }
-  getIdByName(name) {
-    return Object.entries(this.symbolIdMap).find(([, {
-      qualifiedName
-    }]) => qualifiedName === name)?.[0];
-  }
-  getTypeDocById(id) {
-    return this.idToReference[id];
-  }
-  *generateOID() {
-    let id = 1;
-    while (true) {
-      yield id++;
+    /**
+     * Returns automatically incrementing OID. Every call to this function will return a new unique OID.
+     * @returns {number} The OID.
+     */
+    getNewId() {
+        return this.oidGenerator.next().value;
     }
-  }
-}
-;
-class DocspecTransformer {
-  pythonTypeResolver;
-  inheritanceGraph;
-  symbolIdTracker;
-  moduleShortcuts;
-  gitRevision;
-
-  /**
-   * Stack of the docstrings of the current context.
-   *
-   * Used to read the class Google-style docstrings from the class' properties and methods.
-   */
-  contextStack = [];
-  settings = {
-    useDocsGroup: false
-  };
-  constructor({
-    moduleShortcuts,
-    gitRevision
-  }) {
-    this.pythonTypeResolver = new index.PythonTypeResolver();
-    this.symbolIdTracker = new SymbolIdTracker();
-    this.inheritanceGraph = new inheritance.InheritanceGraph(this.symbolIdTracker);
-    this.moduleShortcuts = moduleShortcuts ?? {};
-    this.gitRevision = gitRevision;
-  }
-  transform(docspecModules) {
-    // Root object of the Typedoc structure, accumulator for the recursive walk
-    const typedocApiReference = {
-      children: [],
-      flags: {},
-      groups: [],
-      id: 0,
-      kind: 1,
-      kindString: 'Project',
-      name: 'apify-client',
-      sources: [{
-        character: 0,
-        fileName: 'src/index.ts',
-        line: 1
-      }],
-      symbolIdMap: this.symbolIdTracker.symbolIdMap
-    };
-    this.settings.useDocsGroup = utils.projectUsesDocsGroupDecorator(docspecModules);
-
-    // Convert all the modules, store them in the root object
-    for (const module of docspecModules) {
-      this.walkAndTransform({
-        currentDocspecNode: module,
-        moduleName: module.name,
-        parentTypeDoc: typedocApiReference
-      });
-    }
-    this.inheritanceGraph.resolveInheritance();
-    this.pythonTypeResolver.resolveTypes();
-    this.fixRefs(typedocApiReference);
-    utils.sortChildren(typedocApiReference);
-    this.unpackKwargs();
-    return typedocApiReference;
-  }
-  getContext() {
-    return this.contextStack[this.contextStack.length - 1];
-  }
-  popContext() {
-    this.contextStack.pop();
-  }
-  newContext(context) {
-    this.contextStack.push(context);
-  }
-  unpackKwargs() {
-    const signatures = this.symbolIdTracker.getMethodSignatures();
-    for (const sig of signatures) {
-      const unpackedParams = [];
-      for (const param of sig.parameters ?? []) {
-        if (param.type.type !== 'reference' || param.type?.name !== 'Unpack') {
-          unpackedParams.push(param);
-          // eslint-disable-next-line no-continue
-          continue;
+    addNewReference(object) {
+        var _a, _b, _c, _d;
+        if ((_b = (_a = object.sources) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.fileName) {
+            this.symbolIdMap[object.id] = {
+                qualifiedName: object.name,
+                sourceFileName: (_d = (_c = object.sources) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.fileName,
+            };
         }
-        const typedDict = this.symbolIdTracker.getTypeDocById(
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-        param.type.typeArguments[0]?.target
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument
-        ?? this.symbolIdTracker.getIdByName(param.type.typeArguments[0]?.name));
-        unpackedParams.push(...(typedDict?.children.map(x => _objectSpread(_objectSpread({}, x), {}, {
-          flags: {
-            'keyword-only': true,
-            optional: true
-          }
-        })) ?? []));
-      }
-      sig.parameters = unpackedParams;
+        this.idToReference[object.id] = object;
     }
-  }
-
-  /**
-   * Recursively traverse the Typedoc structure and fix the references to the named entities.
-   *
-   * Searches for the {@link TypeDocType} structure with the `type` property set to `reference`, and replaces the `target` property
-   * with the corresponding ID of the named entity.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  fixRefs(obj) {
-    for (const key of Object.keys(obj)) {
-      if (key === 'name' && obj?.type === 'reference' && this.symbolIdTracker.getIdByName(obj?.name ?? '')) {
-        obj.target = this.symbolIdTracker.getIdByName(obj?.name ?? '');
-      }
-      if (typeof obj[key] === 'object' && obj[key] !== null) {
-        this.fixRefs(obj[key]);
-      }
+    getMethodSignatures() {
+        return Object.values(this.idToReference).filter(({ kindString }) => kindString === 'Call signature');
     }
-  }
-  makeMethodSignature(docspecObject, docstring) {
-    const methodTypeDoc = {
-      comment: docstring.text ? {
-        blockTags: docstring?.returns ? [{
-          content: [{
-            kind: 'text',
-            text: docstring.returns
-          }],
-          tag: '@returns'
-        }] : undefined,
-        summary: [{
-          kind: 'text',
-          text: docstring?.text
-        }]
-      } : undefined,
-      flags: {},
-      id: this.symbolIdTracker.getNewId(),
-      kind: 4096,
-      kindString: 'Call signature',
-      modifiers: docspecObject.modifiers ?? [],
-      name: docspecObject.name,
-      parameters: docspecObject.args?.filter(arg => arg.name !== 'self' && arg.name !== 'cls').map(arg => {
-        const paramTypeDoc = {
-          comment: docstring.args?.[arg.name] ? {
-            summary: [{
-              kind: 'text',
-              text: docstring.args[arg.name]
-            }]
-          } : undefined,
-          defaultValue: arg.default_value,
-          flags: {
-            isOptional: arg.datatype?.includes('Optional') || arg.default_value !== undefined,
-            'keyword-only': arg.type === 'KEYWORD_ONLY'
-          },
-          id: this.symbolIdTracker.getNewId(),
-          kind: 32_768,
-          kindString: 'Parameter',
-          name: arg.name,
-          type: this.pythonTypeResolver.registerType(arg.datatype)
-        };
-        this.symbolIdTracker.addNewReference(paramTypeDoc);
-        return paramTypeDoc;
-      }),
-      type: this.pythonTypeResolver.registerType(docspecObject.return_type)
-    };
-    this.symbolIdTracker.addNewReference(methodTypeDoc);
-    return methodTypeDoc;
-  }
-
-  /**
-   * Given a docspec object outputted by `pydoc-markdown`, transforms this object into the Typedoc structure,
-   * and appends it as a child of the `parentTypeDoc` Typedoc object (which serves as an accumulator for the recursion).
-   * @param obj
-   * @param parent
-   * @param module
-   */
-  walkAndTransform({
-    currentDocspecNode,
-    parentTypeDoc,
-    moduleName
-  }) {
-    if (currentDocspecNode?.datatype === 'TypeAlias') {
-      this.pythonTypeResolver.registerType(currentDocspecNode.value, currentDocspecNode.name);
+    getIdByName(name) {
+        var _a;
+        return (_a = Object.entries(this.symbolIdMap).find(([, { qualifiedName }]) => qualifiedName === name)) === null || _a === void 0 ? void 0 : _a[0];
     }
-    if (utils.isHidden(currentDocspecNode)) {
-      for (const docspecMember of currentDocspecNode.members ?? []) {
-        this.walkAndTransform({
-          currentDocspecNode: docspecMember,
-          moduleName,
-          // Skips the hidden member, i.e. its children will be appended to the parent of the hidden member
-          parentTypeDoc
-        });
-      }
-      return;
+    getTypeDocById(id) {
+        return this.idToReference[id];
     }
-    const _this$getTypedocType = this.getTypedocType(currentDocspecNode, parentTypeDoc),
-      typedocType = _this$getTypedocType.typedocType,
-      typedocKind = _this$getTypedocType.typedocKind;
-    const _this$getGitHubUrls = this.getGitHubUrls(currentDocspecNode),
-      filePathInRepo = _this$getGitHubUrls.filePathInRepo;
-    currentDocspecNode.parsedDocstring = this.parseDocstring(currentDocspecNode);
-    const isOverloadedMethod = typedocKind.kindString === 'Method' && utils.isOverload(currentDocspecNode);
-    if (isOverloadedMethod) {
-      parentTypeDoc.overloads ??= [];
-      parentTypeDoc.overloads.push(currentDocspecNode);
-      return;
+    *generateOID() {
+        let id = 1;
+        while (true) {
+            yield id++;
+        }
     }
-    const currentId = this.symbolIdTracker.getNewId();
-
-    // Get the module name of the member, and check if it has a shortcut (reexport from an ancestor module)
-    const fullName = `${moduleName}.${currentDocspecNode.name}`;
-    if (fullName in this.moduleShortcuts) {
-      moduleName = this.moduleShortcuts[fullName].replace(`.${currentDocspecNode.name}`, '');
+}
+;
+export class DocspecTransformer {
+    constructor({ moduleShortcuts, gitRevision }) {
+        /**
+         * Stack of the docstrings of the current context.
+         *
+         * Used to read the class Google-style docstrings from the class' properties and methods.
+         */
+        this.contextStack = [];
+        this.settings = { useDocsGroup: false };
+        this.pythonTypeResolver = new PythonTypeResolver();
+        this.symbolIdTracker = new SymbolIdTracker();
+        this.inheritanceGraph = new InheritanceGraph(this.symbolIdTracker);
+        this.moduleShortcuts = moduleShortcuts !== null && moduleShortcuts !== void 0 ? moduleShortcuts : {};
+        this.gitRevision = gitRevision;
     }
-    currentDocspecNode.name = currentDocspecNode.decorations?.find(d => d.name === 'docs_name')?.args.slice(2, -2) ?? currentDocspecNode.name;
-
-    // Create the Typedoc member object
-    const currentTypedocNode = _objectSpread(_objectSpread({}, typedocKind), {}, {
-      children: [],
-      comment: currentDocspecNode.parsedDocstring ? {
-        summary: [{
-          kind: 'text',
-          text: currentDocspecNode.parsedDocstring.text
-        }]
-      } : undefined,
-      decorations: currentDocspecNode.decorations?.map(({
-        name,
-        args
-      }) => ({
-        args,
-        name
-      })),
-      flags: {},
-      groups: [],
-      id: currentId,
-      module: moduleName,
-      // This is an extension to the original Typedoc structure, to support showing where the member is exported from
-      name: currentDocspecNode.name,
-      parsedDocstring: currentDocspecNode.parsedDocstring,
-      sources: [{
-        character: 1,
-        fileName: filePathInRepo,
-        gitRevision: this.gitRevision,
-        line: currentDocspecNode.location.lineno
-      }],
-      type: typedocType
-    });
-    this.symbolIdTracker.addNewReference(currentTypedocNode);
-    if (currentTypedocNode.kindString === 'Method') {
-      currentTypedocNode.signatures = [this.makeMethodSignature(currentDocspecNode, currentDocspecNode.parsedDocstring)];
+    transform(docspecModules) {
+        // Root object of the Typedoc structure, accumulator for the recursive walk
+        const typedocApiReference = {
+            children: [],
+            flags: {},
+            groups: [],
+            id: 0,
+            kind: 1,
+            kindString: 'Project',
+            name: 'apify-client',
+            sources: [
+                {
+                    character: 0,
+                    fileName: 'src/index.ts',
+                    line: 1,
+                },
+            ],
+            symbolIdMap: this.symbolIdTracker.symbolIdMap,
+        };
+        this.settings.useDocsGroup = projectUsesDocsGroupDecorator(docspecModules);
+        // Convert all the modules, store them in the root object
+        for (const module of docspecModules) {
+            this.walkAndTransform({
+                currentDocspecNode: module,
+                moduleName: module.name,
+                parentTypeDoc: typedocApiReference,
+            });
+        }
+        this.inheritanceGraph.resolveInheritance();
+        this.pythonTypeResolver.resolveTypes();
+        this.fixRefs(typedocApiReference);
+        sortChildren(typedocApiReference);
+        this.unpackKwargs();
+        return typedocApiReference;
+    }
+    getContext() {
+        return this.contextStack[this.contextStack.length - 1];
     }
-    if (currentTypedocNode.kindString === 'Class') {
-      this.newContext(currentDocspecNode.parsedDocstring);
+    popContext() {
+        this.contextStack.pop();
     }
-    for (const docspecMember of currentDocspecNode.members ?? []) {
-      this.walkAndTransform({
-        currentDocspecNode: docspecMember,
-        moduleName,
-        parentTypeDoc: currentTypedocNode
-      });
+    newContext(context) {
+        this.contextStack.push(context);
     }
-    if (currentTypedocNode.kindString === 'Class') {
-      this.popContext();
-      if (currentDocspecNode.bases && currentDocspecNode.bases.length > 0) {
-        for (const base of currentDocspecNode.bases) {
-          const canonicalAncestorType = this.pythonTypeResolver.getBaseType(base);
-          this.inheritanceGraph.addRelationship(canonicalAncestorType, currentTypedocNode);
+    unpackKwargs() {
+        var _a, _b, _c, _d, _e, _f;
+        const signatures = this.symbolIdTracker.getMethodSignatures();
+        for (const sig of signatures) {
+            const unpackedParams = [];
+            for (const param of (_a = sig.parameters) !== null && _a !== void 0 ? _a : []) {
+                if (param.type.type !== 'reference' || ((_b = param.type) === null || _b === void 0 ? void 0 : _b.name) !== 'Unpack') {
+                    unpackedParams.push(param);
+                    // eslint-disable-next-line no-continue
+                    continue;
+                }
+                const typedDict = this.symbolIdTracker.getTypeDocById((
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                (_d = (_c = param.type.typeArguments[0]) === null || _c === void 0 ? void 0 : _c.target) !== null && _d !== void 0 ? _d : this.symbolIdTracker.getIdByName((_e = param.type.typeArguments[0]) === null || _e === void 0 ? void 0 : _e.name)));
+                unpackedParams.push(...((_f = typedDict === null || typedDict === void 0 ? void 0 : typedDict.children.map((x) => (Object.assign(Object.assign({}, x), { flags: { 'keyword-only': true, optional: true } })))) !== null && _f !== void 0 ? _f : []));
+            }
+            sig.parameters = unpackedParams;
         }
-      }
-      for (const overload of currentTypedocNode.overloads ?? []) {
-        const baseMethod = currentTypedocNode.children?.find(child => child.name === overload.name && child.kindString === 'Method' && child.decorations.every(d => d.name !== 'overload'));
-        if (baseMethod) {
-          baseMethod.signatures?.push(this.makeMethodSignature(overload, overload.parsedDocstring.text.length > 0 ? overload.parsedDocstring : baseMethod.parsedDocstring));
-        } else {
-          console.warn(`Method ${overload.name} not found in class ${currentTypedocNode.name} (but overload ${overload.name} exists).`);
+    }
+    /**
+     * Recursively traverse the Typedoc structure and fix the references to the named entities.
+     *
+     * Searches for the {@link TypeDocType} structure with the `type` property set to `reference`, and replaces the `target` property
+     * with the corresponding ID of the named entity.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fixRefs(obj) {
+        var _a, _b;
+        for (const key of Object.keys(obj)) {
+            if (key === 'name' && (obj === null || obj === void 0 ? void 0 : obj.type) === 'reference' && this.symbolIdTracker.getIdByName((_a = obj === null || obj === void 0 ? void 0 : obj.name) !== null && _a !== void 0 ? _a : '')) {
+                obj.target = this.symbolIdTracker.getIdByName((_b = obj === null || obj === void 0 ? void 0 : obj.name) !== null && _b !== void 0 ? _b : '');
+            }
+            if (typeof obj[key] === 'object' && obj[key] !== null) {
+                this.fixRefs(obj[key]);
+            }
         }
-      }
-      currentTypedocNode.overloads = undefined;
-      this.inheritanceGraph.registerNode(currentTypedocNode);
     }
-    const _utils$getGroupName = utils.getGroupName(currentTypedocNode),
-      groupName = _utils$getGroupName.groupName,
-      groupSource = _utils$getGroupName.source;
-    if (groupName && (
-    // If the group comes from a decorator, use it always; otherwise check if the symbol isn't top-level
-    !this.settings.useDocsGroup || groupSource === 'decorator' || parentTypeDoc.kindString !== 'Project') && !isOverloadedMethod) {
-      const group = parentTypeDoc.groups?.find(g => g.title === groupName);
-      if (group) {
-        group.children.push(currentTypedocNode.id);
-      } else {
-        parentTypeDoc.groups?.push({
-          children: [currentTypedocNode.id],
-          title: groupName
-        });
-      }
+    makeMethodSignature(docspecObject, docstring) {
+        var _a, _b;
+        const methodTypeDoc = {
+            comment: docstring.text
+                ? {
+                    blockTags: (docstring === null || docstring === void 0 ? void 0 : docstring.returns)
+                        ? [{ content: [{ kind: 'text', text: docstring.returns }], tag: '@returns' }]
+                        : undefined,
+                    summary: [
+                        {
+                            kind: 'text',
+                            text: docstring === null || docstring === void 0 ? void 0 : docstring.text,
+                        },
+                    ],
+                }
+                : undefined,
+            flags: {},
+            id: this.symbolIdTracker.getNewId(),
+            kind: 4096,
+            kindString: 'Call signature',
+            modifiers: (_a = docspecObject.modifiers) !== null && _a !== void 0 ? _a : [],
+            name: docspecObject.name,
+            parameters: (_b = docspecObject.args) === null || _b === void 0 ? void 0 : _b.filter((arg) => arg.name !== 'self' && arg.name !== 'cls').map((arg) => {
+                var _a, _b;
+                const paramTypeDoc = {
+                    comment: ((_a = docstring.args) === null || _a === void 0 ? void 0 : _a[arg.name])
+                        ? {
+                            summary: [
+                                {
+                                    kind: 'text',
+                                    text: docstring.args[arg.name],
+                                },
+                            ],
+                        }
+                        : undefined,
+                    defaultValue: arg.default_value,
+                    flags: {
+                        isOptional: ((_b = arg.datatype) === null || _b === void 0 ? void 0 : _b.includes('Optional')) || arg.default_value !== undefined,
+                        'keyword-only': arg.type === 'KEYWORD_ONLY',
+                    },
+                    id: this.symbolIdTracker.getNewId(),
+                    kind: 32768,
+                    kindString: 'Parameter',
+                    name: arg.name,
+                    type: this.pythonTypeResolver.registerType(arg.datatype),
+                };
+                this.symbolIdTracker.addNewReference(paramTypeDoc);
+                return paramTypeDoc;
+            }),
+            type: this.pythonTypeResolver.registerType(docspecObject.return_type),
+        };
+        this.symbolIdTracker.addNewReference(methodTypeDoc);
+        return methodTypeDoc;
     }
-    parentTypeDoc.children?.push(currentTypedocNode);
-    utils.sortChildren(currentTypedocNode);
-  }
-
-  // Get the URL of the member in GitHub
-  getGitHubUrls(docspecMember) {
-    const filePathInRepo = docspecMember.location.filename.replace(consts.REPO_ROOT_PLACEHOLDER, '');
-    return {
-      filePathInRepo
-    };
-  }
-
-  /**
-   * If possible, parses the `.docstring` property of the passed object. If the docstring is a stringified JSON object,
-   * it extracts the `args` and `returns` sections and adds them to the returned object.
-   *
-   * TODO
-   * This structure is created in the `google` docstring format, which is a JSON object with the following structure:
-   */
-  parseDocstring(docspecMember) {
-    const docstring = {
-      text: docspecMember.docstring?.content ?? ''
-    };
-    try {
-      const parsedDocstring = JSON.parse(docstring.text);
-      docstring.text = parsedDocstring.text;
-      const parsedArguments = parsedDocstring.sections?.find(section => Object.keys(section)[0] === 'Arguments')?.Arguments ?? [];
-      docstring.args = parsedArguments?.reduce((acc, arg) => {
-        acc[arg.param] = arg.desc;
-        return acc;
-      }, {}) ?? {};
-      const returnTypes = docstring.sections?.find(section => Object.keys(section)[0] === 'Returns')?.Returns ?? [];
-      docstring.returns = returnTypes.join('\n');
-    } catch {
-      // Do nothing
+    /**
+     * Given a docspec object outputted by `pydoc-markdown`, transforms this object into the Typedoc structure,
+     * and appends it as a child of the `parentTypeDoc` Typedoc object (which serves as an accumulator for the recursion).
+     * @param obj
+     * @param parent
+     * @param module
+     */
+    walkAndTransform({ currentDocspecNode, parentTypeDoc, moduleName, }) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+        if ((currentDocspecNode === null || currentDocspecNode === void 0 ? void 0 : currentDocspecNode.datatype) === 'TypeAlias') {
+            this.pythonTypeResolver.registerType(currentDocspecNode.value, currentDocspecNode.name);
+        }
+        if (isHidden(currentDocspecNode)) {
+            for (const docspecMember of (_a = currentDocspecNode.members) !== null && _a !== void 0 ? _a : []) {
+                this.walkAndTransform({
+                    currentDocspecNode: docspecMember,
+                    moduleName,
+                    // Skips the hidden member, i.e. its children will be appended to the parent of the hidden member
+                    parentTypeDoc,
+                });
+            }
+            return;
+        }
+        const { typedocType, typedocKind } = this.getTypedocType(currentDocspecNode, parentTypeDoc);
+        const { filePathInRepo } = this.getGitHubUrls(currentDocspecNode);
+        currentDocspecNode.parsedDocstring = this.parseDocstring(currentDocspecNode);
+        const isOverloadedMethod = typedocKind.kindString === 'Method' && isOverload(currentDocspecNode);
+        if (isOverloadedMethod) {
+            (_b = parentTypeDoc.overloads) !== null && _b !== void 0 ? _b : (parentTypeDoc.overloads = []);
+            parentTypeDoc.overloads.push(currentDocspecNode);
+            return;
+        }
+        const currentId = this.symbolIdTracker.getNewId();
+        // Get the module name of the member, and check if it has a shortcut (reexport from an ancestor module)
+        const fullName = `${moduleName}.${currentDocspecNode.name}`;
+        if (fullName in this.moduleShortcuts) {
+            moduleName = this.moduleShortcuts[fullName].replace(`.${currentDocspecNode.name}`, '');
+        }
+        currentDocspecNode.name =
+            (_e = (_d = (_c = currentDocspecNode.decorations) === null || _c === void 0 ? void 0 : _c.find((d) => d.name === 'docs_name')) === null || _d === void 0 ? void 0 : _d.args.slice(2, -2)) !== null && _e !== void 0 ? _e : currentDocspecNode.name;
+        // Create the Typedoc member object
+        const currentTypedocNode = Object.assign(Object.assign({}, typedocKind), { children: [], comment: currentDocspecNode.parsedDocstring
+                ? {
+                    summary: [
+                        {
+                            kind: 'text',
+                            text: currentDocspecNode.parsedDocstring.text,
+                        },
+                    ],
+                }
+                : undefined, decorations: (_f = currentDocspecNode.decorations) === null || _f === void 0 ? void 0 : _f.map(({ name, args }) => ({ args, name })), flags: {}, groups: [], id: currentId, module: moduleName, name: currentDocspecNode.name, parsedDocstring: currentDocspecNode.parsedDocstring, sources: [
+                {
+                    character: 1,
+                    fileName: filePathInRepo,
+                    gitRevision: this.gitRevision,
+                    line: currentDocspecNode.location.lineno,
+                },
+            ], type: typedocType });
+        this.symbolIdTracker.addNewReference(currentTypedocNode);
+        if (currentTypedocNode.kindString === 'Method') {
+            currentTypedocNode.signatures = [
+                this.makeMethodSignature(currentDocspecNode, currentDocspecNode.parsedDocstring),
+            ];
+        }
+        if (currentTypedocNode.kindString === 'Class') {
+            this.newContext(currentDocspecNode.parsedDocstring);
+        }
+        for (const docspecMember of (_g = currentDocspecNode.members) !== null && _g !== void 0 ? _g : []) {
+            this.walkAndTransform({
+                currentDocspecNode: docspecMember,
+                moduleName,
+                parentTypeDoc: currentTypedocNode,
+            });
+        }
+        if (currentTypedocNode.kindString === 'Class') {
+            this.popContext();
+            if (currentDocspecNode.bases && currentDocspecNode.bases.length > 0) {
+                for (const base of currentDocspecNode.bases) {
+                    const canonicalAncestorType = this.pythonTypeResolver.getBaseType(base);
+                    this.inheritanceGraph.addRelationship(canonicalAncestorType, currentTypedocNode);
+                }
+            }
+            for (const overload of (_h = currentTypedocNode.overloads) !== null && _h !== void 0 ? _h : []) {
+                const baseMethod = (_j = currentTypedocNode.children) === null || _j === void 0 ? void 0 : _j.find((child) => child.name === overload.name && child.kindString === 'Method' && child.decorations.every((d) => d.name !== 'overload'));
+                if (baseMethod) {
+                    (_k = baseMethod.signatures) === null || _k === void 0 ? void 0 : _k.push(this.makeMethodSignature(overload, overload.parsedDocstring.text.length > 0 ?
+                        overload.parsedDocstring :
+                        baseMethod.parsedDocstring));
+                }
+                else {
+                    console.warn(`Method ${overload.name} not found in class ${currentTypedocNode.name} (but overload ${overload.name} exists).`);
+                }
+            }
+            currentTypedocNode.overloads = undefined;
+            this.inheritanceGraph.registerNode(currentTypedocNode);
+        }
+        const { groupName, source: groupSource } = getGroupName(currentTypedocNode);
+        if (groupName && // If the group comes from a decorator, use it always; otherwise check if the symbol isn't top-level
+            (!this.settings.useDocsGroup ||
+                groupSource === 'decorator' ||
+                parentTypeDoc.kindString !== 'Project')
+            && !isOverloadedMethod) {
+            const group = (_l = parentTypeDoc.groups) === null || _l === void 0 ? void 0 : _l.find((g) => g.title === groupName);
+            if (group) {
+                group.children.push(currentTypedocNode.id);
+            }
+            else {
+                (_m = parentTypeDoc.groups) === null || _m === void 0 ? void 0 : _m.push({
+                    children: [currentTypedocNode.id],
+                    title: groupName,
+                });
+            }
+        }
+        (_o = parentTypeDoc.children) === null || _o === void 0 ? void 0 : _o.push(currentTypedocNode);
+        sortChildren(currentTypedocNode);
     }
-    if (!docstring.text) {
-      docstring.text = this.getContext()?.args?.[docspecMember.name] ?? '';
+    // Get the URL of the member in GitHub
+    getGitHubUrls(docspecMember) {
+        const filePathInRepo = docspecMember.location.filename.replace(REPO_ROOT_PLACEHOLDER, '');
+        return { filePathInRepo };
     }
-    return docstring;
-  }
-
-  /**
-   * Given the current Docspec object and the parent Typedoc object, returns the Typedoc type and kind of the current object.
-   */
-  getTypedocType(docspecMember, parentTypeDoc) {
-    let typedocKind = consts.TYPEDOC_KINDS[docspecMember.type];
-    if (docspecMember.bases?.includes('Enum')) {
-      typedocKind = consts.TYPEDOC_KINDS.enum;
+    /**
+     * Converts a docstring section to Docusaurus admonition markdown format.
+     */
+    sectionToAdmonition(sectionName, content) {
+        const admonitionType = DocspecTransformer.SECTION_TO_ADMONITION[sectionName];
+        if (!admonitionType) {
+            return '';
+        }
+        const contentText = content
+            .map((item) => {
+            if (typeof item === 'string') {
+                return item;
+            }
+            if (typeof item === 'object' && item !== null && 'desc' in item) {
+                const obj = item;
+                return obj.param ? `**${obj.param}**: ${obj.desc}` : obj.desc;
+            }
+            return '';
+        })
+            .filter(Boolean)
+            .join('\n');
+        if (!contentText) {
+            return '';
+        }
+        return `:::${admonitionType} ${sectionName}\n${contentText}\n:::`;
     }
-    let typedocType = this.pythonTypeResolver.registerType(docspecMember.datatype);
-    if (docspecMember.decorations?.some(d => ['property', 'dualproperty'].includes(d.name))) {
-      typedocKind = consts.TYPEDOC_KINDS.data;
-      typedocType = this.pythonTypeResolver.registerType(docspecMember.return_type ?? docspecMember.datatype);
+    /**
+     * If possible, parses the `.docstring` property of the passed object. If the docstring is a stringified JSON object,
+     * it extracts the `args` and `returns` sections and adds them to the returned object.
+     *
+     * The docstring format is a JSON object with a `content` array that contains interleaved text strings
+     * and section objects, preserving the original order from the docstring.
+     */
+    parseDocstring(docspecMember) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const docstring = { text: (_b = (_a = docspecMember.docstring) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : '' };
+        try {
+            const parsedDocstring = JSON.parse(docstring.text);
+            // Build the text output by processing content items in order
+            const textParts = [];
+            for (const item of (_c = parsedDocstring.content) !== null && _c !== void 0 ? _c : []) {
+                if (typeof item === 'string') {
+                    // Regular text content
+                    textParts.push(item);
+                }
+                else {
+                    // Section object
+                    const sectionName = Object.keys(item)[0];
+                    const sectionContent = item[sectionName];
+                    if (sectionName === 'Arguments') {
+                        // Extract arguments for parameter documentation
+                        const parsedArguments = sectionContent;
+                        docstring.args =
+                            (_d = parsedArguments === null || parsedArguments === void 0 ? void 0 : parsedArguments.reduce((acc, arg) => {
+                                acc[arg.param] = arg.desc;
+                                return acc;
+                            }, {})) !== null && _d !== void 0 ? _d : {};
+                    }
+                    else if (sectionName === 'Returns') {
+                        // Extract return type documentation
+                        docstring.returns = sectionContent
+                            .map((returnsItem) => {
+                            if (typeof returnsItem === 'string') {
+                                return returnsItem;
+                            }
+                            if (typeof returnsItem === 'object' && returnsItem !== null && 'param' in returnsItem && 'desc' in returnsItem) {
+                                const obj = returnsItem;
+                                return `${obj.param}: ${obj.desc}`;
+                            }
+                            return '';
+                        })
+                            .filter(Boolean)
+                            .join('\n');
+                    }
+                    else {
+                        // Convert other sections to admonitions inline
+                        const admonition = this.sectionToAdmonition(sectionName, sectionContent);
+                        if (admonition) {
+                            textParts.push(admonition);
+                        }
+                    }
+                }
+            }
+            docstring.text = textParts.join('\n\n');
+        }
+        catch (_h) {
+            // Do nothing
+        }
+        if (!docstring.text) {
+            docstring.text = (_g = (_f = (_e = this.getContext()) === null || _e === void 0 ? void 0 : _e.args) === null || _f === void 0 ? void 0 : _f[docspecMember.name]) !== null && _g !== void 0 ? _g : '';
+        }
+        return docstring;
     }
-    if (parentTypeDoc.kindString === 'Enumeration') {
-      typedocKind = consts.TYPEDOC_KINDS.enumValue;
-      typedocType = {
-        type: 'literal',
-        value: docspecMember.value
-      };
+    /**
+     * Given the current Docspec object and the parent Typedoc object, returns the Typedoc type and kind of the current object.
+     */
+    getTypedocType(docspecMember, parentTypeDoc) {
+        var _a, _b, _c;
+        let typedocKind = TYPEDOC_KINDS[docspecMember.type];
+        if ((_a = docspecMember.bases) === null || _a === void 0 ? void 0 : _a.includes('Enum')) {
+            typedocKind = TYPEDOC_KINDS.enum;
+        }
+        let typedocType = this.pythonTypeResolver.registerType(docspecMember.datatype);
+        if ((_b = docspecMember.decorations) === null || _b === void 0 ? void 0 : _b.some((d) => ['property', 'dualproperty'].includes(d.name))) {
+            typedocKind = TYPEDOC_KINDS.data;
+            typedocType = this.pythonTypeResolver.registerType((_c = docspecMember.return_type) !== null && _c !== void 0 ? _c : docspecMember.datatype);
+        }
+        if (parentTypeDoc.kindString === 'Enumeration') {
+            typedocKind = TYPEDOC_KINDS.enumValue;
+            typedocType = {
+                type: 'literal',
+                value: docspecMember.value,
+            };
+        }
+        return { typedocKind, typedocType };
     }
-    return {
-      typedocKind,
-      typedocType
-    };
-  }
 }
-exports.DocspecTransformer = DocspecTransformer;
-exports.SymbolIdTracker = SymbolIdTracker;
-//# sourceMappingURL=transformation.js.map
+/**
+ * Maps Google-style docstring section names to Docusaurus admonition types.
+ * Only sections that semantically match admonition purposes are included.
+ * Sections like Raises, Yields, Attributes are technical documentation, not admonitions.
+ */
+DocspecTransformer.SECTION_TO_ADMONITION = {
+    Danger: 'danger',
+    Info: 'info',
+    Note: 'note',
+    Tip: 'tip',
+    Warning: 'warning',
+};
+//# sourceMappingURL=transformation.js.map