Automated component docs ADR

[mperrotti]

These changes propose an ADR to help us resolve https://github.com/github/primer/issues/3258 using automation tools such as react-docgen-typescript.

Related PR: https://github.com/primer/react/pull/4466

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 6187ec8236bc4451bfdefe0e86eec16c785146dd

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

[github-actions[bot]]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	102.49 KB (0%)
packages/react/dist/browser.umd.js	102.85 KB (0%)

[mperrotti]

@joshblack and other reviewers - I'd really love to come to a decision with this ADR so we can fix our component prop docs.

If we reject the ADR, I'll use my work on https://github.com/primer/react/pull/4466 to manually update inaccurate .docs.json files.

If we approve the ADR, I'll apply all the feedback to https://github.com/primer/react/pull/4466 so we can get it reviewed and merged.

---

These two questions are my biggest blockers:

• How we should transition from the current components.json output to the new improved components.json output. In this comment we decided we'll slowly remove *.docs.json files, but I still have some questions:
  • Should we have two components.json files? Or just keep the one at generated/components.json? My preference is to keep the existing one
  • How might we plan the slow removal of *.docs.json files into our usual work streams?
• How we do want to handle generating and snapshot-testing components.json?
  • Require contributors to run the script locally?
  • GitHub action like we do for VRT snapshots?

[francinelucca]

I think the automation-route sounds great! Especially if we can complement with manual documentation for the (hopefully) few components that don't follow the "happy path", also wondering if we have a rough idea of how many those would be 👀. Some thoughts:

• A Github action to snapshot test against components.json sounds good to me.
• Agree with @joshblack here on slow phase-out of individual component docs.
• Regarding modifying the author experience, wondering just how cumbersome that would be? is it just relating to the way the components are exported as explained in the Gotchas/workarounds and adding the JSDocs updates, or is there more to it?
• Also think one components.json file probably makes sense if we followed the proposed rollout plan of using a script action to build, monitor and improve the automation until we're happy with it and ready to switch over.

[mperrotti]

Regarding https://github.com/primer/react/pull/4727#discussion_r1671099407, wondering just how cumbersome that would be? is it just relating to the way the components are exported as explained in the Gotchas/workarounds and adding the JSDocs updates, or is there more to it?

Nope, there's nothing more to it than that.

[mperrotti]

Closing this until we revisit