feat(docusaurus-theme): redirect to GH using types definition

[weronikaolejniczak]

Summary

On this PR, I:

• generate type data with typedoc@latest to use in the documentation (eui-docgen (react-docgen-typescript) doesn't provide data for types, interfaces, hooks; partially solves https://github.com/elastic/eui-private/issues/237),
• replace all anchor links in JSDoc comments with the link annotation in packages/eui,
• catch all of the link annotations in: packages/docusaurus-theme/src/components/prop_table/prop_table.tsx#L119-L148 and substitute with a Markdown link ([]() syntax) where the url redirects to the type definition in GitHub gotten from the typedoc-generated JSON file.

Screen.Recording.2025-04-03.at.16.37.26.mov

Closes #8464

QA

Either:

• Do a sanity check with several prop tables

or

• test each page on the documentation site

Pages

• Display

  • Aspect ratio
  • Avatar
  • Callout
  • Card
  • CommentList
  • DescriptionList
  • DragAndDrop
  • Health
  • Image
  • ListGroup
  • Loading
  • Progress
  • Skeleton
  • Stat
  • Text
  • Timeline
  • Title
  • Tooltip
  • Badge
  • BetaBadge
  • NotificationBadge
  • EmptyPrompt
  • Icons
  • Toast
  • Tour

• Editors & Syntax

  • Code
  • Markdown editor
  • Markdown format

• Forms

  • Auto refresh
  • Date picker range
  • Date picker
  • Super date picker
  • Described form group
  • Form control layouts
  • Form label
  • Form row
  • Form validation
  • Numeric > Basic
  • Numeric > Range sliders
  • Other > Color picker
  • Other > File picker
  • Search & Filter > Expression
  • Search & Filter > Filter group
  • Search & Filter > Search bar
  • Search & Filter > Search field
  • Selection > Combo Box
  • Selection > Select
  • Selection > Selectable
  • Selection > Super select
  • Selection > Checkboxes and radios
  • Selection > Switch
  • Text > Basic
  • Text > Inline edit
  • Text > Password

• Layout

  • Accordion
  • Bottom bar
  • Header
  • Horizontal rule
  • Page header
  • Popover
  • Resizable container
  • Spacer
  • Flex > Flex grid
  • Flex > Flex group
  • Flex > Flex item
  • Flyout > Flyout push
  • Flyout > Flyout resizable
  • Flyout
  • Confirm modal
  • Modal
  • Page components
  • Panel
  • Split panel

• Navigation

  • Breadcrumbs
  • Collapsible nav
  • Context menu
  • Facet
  • Key pad menu
  • Link
  • Side nav
  • Tree view
  • Button basic
  • Button empty
  • Button group
  • Button icon
  • Pagination
  • Horizontal steps
  • Steps
  • Tabs

• Tabular content

  • Data grid
  • Data grid > Cells and popover
  • Data grid > Container constraints
  • Data grid > Schema and columns
  • Data grid > Style and display
  • Data grid > Toolbar
  • Data grid > In memory
  • Data grid > Ref
  • Data grid > Custom body rendering
  • Tables > Basic tables
  • Tables > Custom tables
  • Tables > In-memory tables
  • Tables > Custom cell rendering
  • Tables > Sorting and filtering
  • Tables > Pagination
  • Tables > Row selection
  • Tables > Table actions
  • Tables > Fixed header/columns
  • Tables > Virtual scrolling
  • Tables > Drag and drop rows
  • Tables > Expandable rows

• Templates

  • Sitewide search
  • Page template
  • Breakpoints > Utilities

• Utilities

  • Auto sizer
  • Beacon
  • Copy
  • Delay
  • Error boundary
  • Highlight and mark
  • HTML id generator
  • i18n
  • Inner text
  • Mutation observer
  • Outside click detector
  • Overlay mask
  • Portal
  • Pretty duration
  • Provider
  • Resize observer
  • Text diff
  • Text truncation
  • Accessibility
  • Color palettes
  • Focus trap
  • Window events

[weronikaolejniczak]

@acstll you will notice that sometimes there's other JSDoc annotations that do not work (@see aria-labelledby(corrected)), if you have an idea how to tackle this I'm open to doing it on this PR. Maybe we should remove all of them when parsing the description?

Sometimes there are also @see {@link something} which for some reason doesn't parse correctly, those links are skipped. I believe the approach could be improving the regexp OR removing @see before @link in the comments.

Let me know what you think! Looking forward to your review 🙏🏻

If we could move bigger updates to separate tasks that'd be cool as well, so that I am able to wrap this up before EAH.

[acstll]

I tested this thoroughly and it's a really nice improvement, LGTM 🟢

Some notes:

• I think it's OK to replace @see with plain See when it's preceding a {@link …} (JSDoc docs give that impression)
• as discussed offline, external links and other link-like items like @see aria-labelledby can be handled later on, and this PR can focus on internal {@link (\w+)} which works pretty good imho
• probably most external links and similar come from extending types not-in-our-codebase (also discussed offline)

---

only for reference, these are examples of external and link-like items:

ref in https://eui.elastic.co/pr_8543/docs/components/display/badge/#EuiBadgeGroup

@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}

aria-label in many places

@see aria-labelledby.

language in https://eui.elastic.co/pr_8543/docs/components/display/code/#EuiCode

@see https://prismjs.com/#supported-languages for options

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 10535fb
• Documentation website

History

• 💔 Build #260 failed 9561655
• 💚 Build #253 succeeded 255a107
• 💚 Build #199 succeeded 2e6ebb7
• 💔 Build #151 failed f2c043a

cc @weronikaolejniczak

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 10535fb

History

• 💚 Build #3995 succeeded 255a107
• 💚 Build #3966 succeeded 2e6ebb7
• 💚 Build #3931 succeeded f2c043a
• 💔 Build #3817 failed 266c1dc
• 💔 Build #3785 failed 32177e2
• 💔 Build #3776 failed 1cca918

cc @weronikaolejniczak

[acstll]

[bonus comment] while running the typedoc command, we get 415 warnings… I'm wondering how many of those are things that would be beneficial to address, and how many false positives or things we can safely ignore (speaking of which, I'm not familiar with typedoc) — do you think this is something we could address in this PR? later on?

[weronikaolejniczak]

@acstll thanks for reminding me about warnings. I think it's safe to proceed with what we already have but could be beneficial to look through the list. The majority of them are about not exporting an interface or unexpected JSDoc annotations. Potentially something that might not end up in the JSON output and not be linked in the description to GitHub BUT would have to be checked one by one. We can totally do that work on another ticket while already incorporating a lot of value to the docs site with this PR 😄 what do you think?

Side note, these warnings can be silenced.

[acstll]

We can totally do that work on another ticket while already incorporating a lot of value to the docs site with this PR 😄 what do you think?

I agree! 👍