Improve handling of docs from third-party libraries

[laymonage]

Hey, thanks for releasing a new version of the package!

I tried to use it to build Wagtail's docs, but unfortunately encountered a few errors that were raised during the build process due to third-party libraries that we use.

Here are a couple fixes I added to get the build working. Not sure how to write the tests though. Let me know if you'd like any changes!

[laymonage]

I think this comes from React, declarations was undefined.

[laymonage]

I encountered this due to our use of the events library. The CommentDisplayPart was the following:

{
  kind: 'inline-tag',
  tag: '@link',
  text: 'defaultMaxListeners',
  target: DeclarationReflection {
    id: 70,
    name: 'defaultMaxListeners',
    kind: 1024,
    flags: ReflectionFlags { flags: 1048 },
    comment: undefined,
    children: undefined,
    documents: undefined,
    childrenIncludingDocuments: undefined,
    groups: undefined,
    categories: undefined,
    variant: 'declaration',
    sources: [ [SourceReference] ],
    escapedName: 'defaultMaxListeners',
    type: IntrinsicType { name: 'number', type: 'intrinsic' },
    typeParameters: undefined,
    signatures: undefined,
    indexSignatures: undefined,
    getSignature: undefined,
    setSignature: undefined,
    defaultValue: undefined,
    overwrites: undefined,
    inheritedFrom: ReferenceType {
      type: 'reference',
      name: 'Chooser.defaultMaxListeners',
      typeArguments: undefined,
      highlightedProperties: undefined,
      qualifiedName: 'Chooser.defaultMaxListeners',
      package: undefined,
      externalUrl: undefined,
      refersToTypeParameter: false,
      preferValues: false,
      _target: 898
    },
    implementationOf: undefined,
    extendedTypes: undefined,
    extendedBy: undefined,
    implementedTypes: undefined,
    implementedBy: undefined,
    typeHierarchy: undefined,
    readme: undefined,
    packageVersion: undefined
  }
}

I'm not sure whether failing loudly and stopping the build was intentional. If it were, I suppose we can look for alternatives. Maybe handling inline-tag?

I'm pretty sure Wagtail should've used EventTarget rather than events' EventEmitter, so we could also refactor our code instead...

[hoodmane]

We could do something like this:

  return content.map((x): DescriptionItem => {
    switch(x.kind) {
      case "code":
        return { type: "code", code: x.text };
      case "text":
        return { type: "text", text: x.text };
      case "inline-tag":
        return { type: "text", text: x.text };
      case "relative-link":
        return { type: "text", text: x.text };
    }
  });

[hoodmane]

This is a bit lazy, it would be better to add inline-tag and relative-link cases to DescriptionItem, but we could put a TODO here.

[hoodmane]

To test this, add more cases near here:
https://github.com/pyodide/sphinx-js/blob/master/tests/test_typedoc_analysis/source/types.ts?plain=1#L150
and here:
https://github.com/pyodide/sphinx-js/blob/master/tests/test_typedoc_analysis/test_typedoc_analysis.py?plain=1#L618

[hoodmane]

Let's not include this default case because then the typescript typechecker will give a type error if there are cases that we haven't covered.

[laymonage]

Without the default case, TypeScript requires the return value to be Array<DescriptionItem | undefined>. Is that what we want?

[hoodmane]

For me it works fine. Did you run npm i?

[hoodmane]

See #276:
https://github.com/pyodide/sphinx-js/actions/runs/16121106961/job/45486860109#step:6:31
It should typecheck fine if your development environment is set up correctly.

[laymonage]

Ah, sorry about that, thanks! It does work after that, but now it detects relative-link being incorrect because it was added in typedoc 0.26, while our package.json uses typedoc ^0.25.13.

Would you rather drop relative-link, or update typedoc (or maybe add a version check...)? (Also, it seems package-lock.json needs updating...)

[hoodmane]

We can skip the typecheck job against typedoc 0.25 and only run it on the 0.27 and 0.28 jobs.