Automate component documentation

[mperrotti]

I'm trying to automate more of our component documentation by using react-docgen-typscript. This could eliminate the need to maintain {ComponentName}.docs.json files.

See this discussion post for a more detailed overview of this work.

Try it out

npm run build:component-docs-json

Raw Docgen output: packages/react/script/prop-docs/docgen-output.json
With data required by components.json schema: packages/react/script/prop-docs/components.json

Overview

The bulk of the changes in this PR are to make component documentation data parseable by react-docgen and react-typescript-docgen.

The main issue was caused by referencing accessing React's modules directly from the React import. I found 3 ways to work around this:

import React, {forwardRef, type FC, type PropsWithChildren} from 'react'

const PlainComponent: FC<PropsWithChildren<P>> = (props) => {}

const ComponentThatForwardsRef = forwardRef<HTMLElement, P>(
    (props, _ref) => {}
)

import * as React from 'react'

const PlainComponent: React.FC<React.PropsWithChildren<P>> = (props) => {}

const ComponentThatForwardsRef = React.forwardRef<HTMLElement, P>(
    (props, _ref) => {}
)

import React from 'react'

const PlainComponent = (props: P) => {}

const ComponentThatForwardsRef = React.forwardRef(
    (props: P, _ref) => {}
)

Still broken

There are a few files I haven't been able to parse yet.

Skipped entirely by react-docgen-typsecript

Comforting note: We might not even need docs for these because they're only used internally.

• packages/react/src/ActionList/ActionListContainerContext.tsx
• packages/react/src/Autocomplete/AutocompleteContext.tsx
• packages/react/src/Button/ButtonBase.tsx
• packages/react/src/UnderlineNav/UnderlineNavContext.tsx
• packages/react/src/deprecated/Button/ButtonStyles.tsx
• packages/react/src/drafts/MarkdownEditor/_SavedReplies.tsx

Props or args not documented

Comforting note: Some of these components don't have any props besides "children", and some of these files may not even need docs because they're not meant for external use.

• packages/react/src/ActionBar/ActionBar.tsx - ActionBar.Divider
• packages/react/src/Blankslate/Blankslate.tsx - Blankslate.Visual
• packages/react/src/Blankslate/Blankslate.tsx - Blankslate.Description
• packages/react/src/ConfirmationDialog/ConfirmationDialog.tsx - useConfirm
• packages/react/src/DataTable/Table.tsx - Table.Actions
• packages/react/src/DataTable/Table.tsx - Table.Divider
• packages/react/src/DataTable/Table.tsx - Table.Head
• packages/react/src/DataTable/Table.tsx - Table.Body
• packages/react/src/DataTable/Table.tsx - Table.Row
• packages/react/src/DataTable/Table.tsx - Table.CellPlaceholder
• packages/react/src/FormControl/_FormControlContext.tsx - useFormControlContext
• packages/react/src/FormControl/_FormControlContext.tsx - useFormControlForwardedProps
• packages/react/src/FormControl/_FormControlContext.tsx - FormControlContextProvider
• packages/react/src/Portal/Portal.tsx - registerPortalRoot
• packages/react/src/Select/Select.tsx - Select.OptGroup
• packages/react/src/ToggleSwitch/ToggleSwitchStoryWrapper.tsx - ToggleSwitchStoryWrapper
• packages/react/src/UnderlineNav/UnderlineNav.tsx - MoreMenuListItem
• packages/react/src/UnderlineNav/UnderlineNav.tsx - getValidChildren
• packages/react/src/hooks/useMedia.tsx - useMedia
• packages/react/src/utils/form-story-helpers.tsx - getTextInputArgTypes
• packages/react/src/utils/isNumeric.tsx - isNumeric
• packages/react/src/utils/ssr.tsx - SSRProvider
• packages/react/src/utils/ssr.tsx - useSSRSafeId
• packages/react/src/deprecated/ActionList/Divider.tsx - Divider
• packages/react/src/deprecated/ActionList/Divider.tsx - Divider.renderItem
• packages/react/src/deprecated/ActionList/Divider.tsx - StyledDivider
• packages/react/src/drafts/CSSComponent/index.tsx - Component
• packages/react/src/drafts/MarkdownEditor/Toolbar.tsx - MarkdownEditor.DefaultToolbarButtons
• packages/react/src/drafts/SelectPanel2/SelectPanel.tsx - SelectPanel.Footer
• packages/react/src/drafts/SelectPanel2/SelectPanel.tsx - SelectPanel.Loading
• packages/react/src/internal/components/LiveRegion.tsx - LiveRegion
• packages/react/src/internal/components/UnderlineTabbedInterface.tsx - StyledUnderlineItemList
• packages/react/src/internal/components/UnderlineTabbedInterface.tsx - LoadingCounter
• packages/react/src/drafts/MarkdownEditor/suggestions/_useEmojiSuggestions.tsx - useEmojiSuggestions
• packages/react/src/drafts/MarkdownEditor/suggestions/_useMentionSuggestions.tsx - useMentionSuggestions
• packages/react/src/drafts/MarkdownEditor/suggestions/_useReferenceSuggestions.tsx - useReferenceSuggestions
• packages/react/src/internal/components/CheckboxOrRadioGroup/CheckboxOrRadioGroupContext.tsx - Context

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5ded7c0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[camertron]

We really need this, awesome work! Does it make sense to merge this PR in its current state and fill in the missing components later? If so, I'm happy to approve it.

[camertron]

Can we use module imports here instead of require? I see we're using tsx so that should be possible?

[camertron]

Just FYI @broccolinisoup and I just worked up this PR and this PR that introduce a docsId field for grouping related components that have different names, eg. tooltip and tooltip_v2. We'll probably want to generate that field in this script too, although I'm not sure where the data would come from.

[github-actions]

Hi! This pull request has been marked as stale because it has been open with no activity for 60 days. You can comment on the pull request or remove the stale label to keep it open. If you do nothing, this pull request will be closed in 7 days.

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	91.19 KB (-0.03% 🔽)
packages/react/dist/browser.umd.js	91.45 KB (-0.11% 🔽)

[mperrotti]

Closing this until we decide how/if we want to automate component prop docs.

In the meantime, I manually corrected the docs in this PR: #5316