Generate prop documentation #1323

colebemis · 2021-06-24T19:18:14Z

Problem

We're currently maintaining prop documentation manually. This leads to outdated or missing prop documentation which is frustrating for consumers.

Solution

This PR introduces a Props component that we can use in our markdown documentation files to display prop documentation.

Example

`.mdx` file

import {Props} from '../src/props'
import {ActionList} from '@primer/components'

## Props

<Props of={ActionList.Item} />

Output

Next steps

Make the Props component an MDX shortcode so we don't have to import it at the top of every file
Add support for Markdown syntax in prop descriptions
Incrementally migrate component documentation to use the Props component

changeset-bot · 2021-06-24T19:18:16Z

⚠️ No Changeset found

Latest commit: b2a1355

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

vercel · 2021-06-24T19:18:19Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/primer/primer-components/Bir7erchVMwjs2jyiCWZL9iJE98E
✅ Preview: https://primer-components-git-docgen-primer.vercel.app

smockle · 2021-07-01T14:52:21Z

docs/gatsby-node.js

@@ -35,3 +37,65 @@ exports.onCreateWebpackConfig = ({actions, plugins, loaders, getConfig}) => {

  actions.replaceWebpackConfig(config)
 }
+
+exports.sourceNodes = ({actions, createNodeId, createContentDigest}) => {


✍️ Gatsby’s sourceNodes docs: https://www.gatsbyjs.com/docs/reference/config-files/gatsby-node/#sourceNodes

smockle · 2021-07-01T15:02:07Z

docs/package.json

    "react-dom": "^17.0.0",
    "styled-system": "^5.1.0"
  },
  "devDependencies": {
    "cross-env": "7.0.2",
+    "globby": "^11.0.4",


✍️ globby is actively-developed, >40 million weekly downloads, <22 KB unpacked, 6 dependencies, has built-in TypeScript types, is MIT-licensed, I haven’t seen known vulnerabilities, and it doesn’t duplicate functionality built-in to Node.js. 👍

smockle · 2021-07-01T15:12:51Z

docs/gatsby-node.js

+  const files = globby.sync(['../src/**/*.tsx'], {absolute: true})
+  const data = docgen.parse(files, {
+    savePropValueAsString: true,
+    propFilter: prop => {


✍️ react-docgen-typescript’s propFilter docs: https://github.com/styleguidist/react-docgen-typescript#propfilter

smockle · 2021-07-01T15:22:18Z

docs/src/props.js

+export function Props({of}) {
+  const data = useStaticQuery(graphql`
+    query {
+      allComponentMetadata {


✍️ I am not very proficient with GraphQL, so I don’t know what makes allComponentMetadata queryable, but quick searches will show other examples of this pattern, e.g. https://blog-nrrd.doi.gov/implementing-mdx/#Step-1-Using-Gatsbys-GraphQL-to-get-your-components

smockle · 2021-07-01T15:24:11Z

docs/gatsby-node.js

+
+  const components = data.map(component => {
+    return {
+      name: component.displayName,


Does every component have a displayName?

Yes, according to the react-docgen-typescript types: https://github.com/styleguidist/react-docgen-typescript/blob/6c2a088a2ed86dc8f7b23abea50f13ff78825d76/src/parser.ts#L22

smockle · 2021-07-01T15:25:22Z

src/Avatar.tsx

@@ -4,7 +4,9 @@ import sx, {SxProp} from './sx'
 import {ComponentProps} from './utils/types'

 type StyledAvatarProps = {
+  /** Sets the width and height of the avatar. */


Nice, thanks for adding comments here! ✨

smockle · 2021-07-01T15:28:36Z

docs/gatsby-node.js

+        type: `ComponentMetadata`,
+        mediaType: `text/html`,
+        content: nodeContent,
+        contentDigest: createContentDigest(component)


✍️ createContentDigest supports objects: https://github.com/gatsbyjs/gatsby/blob/f4c5c482ba5da626d4f7e2d592fdc4d43eb817ba/packages/gatsby-core-utils/src/create-content-digest.ts#L29-L30 👍

smockle

Let a few non-blocking comments (✍️ indicates comments which may help other reviewers).

Tested this locally:

$ cd docs
$ npm install
$ npm run clean && npm run build
$ npm run clean && npm run develop
# Visited http://localhost:8000/Avatar

Looks good to me! 🚢

* Add new filesystem source * Add component metadata type * Create Props component * Update props table * Handle empty and error states * Add required label * Update required prop styles * Clean up code comments * Remove filesystem plugin * Remove extra markdown file * Add component comment Co-authored-by: Clay Miller <clay@smockle.com>

* add utility props to Box * update box docs * export box props * update snapshots * Create green-worms-nail.md * AvatarStack story in storybook * Update .changeset/green-worms-nail.md Co-authored-by: Cole Bemis <colebemis@github.com> * Update docs/content/Box.md Co-authored-by: Cole Bemis <colebemis@github.com> * Remove duplicate border system prop definitions * Remove duplicate grid system props definitions * Update FlexProps definition * Remove duplicate position system prop definitions * Update Box documentation * Update BoxProps * Update Box docs * Update Box props * fix: Type 'DropdownButton' as 'button' (#1318) * fix: Type 'DropdownButton' as 'button' * chore: Update snapshots * chore: Set test directory via config rather than flag (#1319) * feat(useFocusZone): update active-descendant on mousemove (#1308) * fix: Split `<Item>` labels (#1320) * fix: Separate 'Item' content into 'label' and 'description' * fix: Only add 'aria-describedby' when 'description' exists * fix: Memoize 'id' so 'Item's and labels match * fix: Don’t rely on 'id' which is possibly not globally-unique * fix: Restore semi-full-width 'Item' dividers, without giving up the semantic nesting. By “semantic nesting”, I mean that the 'Item' label and description are now siblings, which is preferable to the previous implementation, where the description node was a child of the label node. As a general principle, we should align DOM hierarchies with information hierarchies. An analogy: If I were using a bulleted list to describe a dog, I would not indent its breed as a second-level bullet beneath the bullet for its name, because a dog’s breed is not dependent/derived data from its name. Similarly, description is not dependent/derived from label, and so should not be nested in DOM. * fix: Reduce styled-components class permutations. https://www.joshwcomeau.com/css/styled-components/ * feat(Overlay): slide away from anchor based on position (#1322) * feat(Overlay): slide away from anchor based on position * fix: handle position changes when re-opening AnchoredOverlay * refactor: use js animation for slide to fix safari * fix: Tests were failing with Axe violations - https://dequeuniversity.com/rules/axe/4.1/aria-dialog-name - https://dequeuniversity.com/rules/axe/4.2/presentation-role-conflict - https://www.w3.org/TR/wai-aria-practices-1.1/examples/menu-button/menu-button-links.html First, 'Overlay's aren’t 'listbox'es, because (when used in 'DropdownMenu' or 'ActionMenu') they contain 'menuitem's, 'menuitemradio's, or 'menuitemcheckbox'es. Second, 'Overlay's aren’t 'dialog's, because (as demonstrated in the WAI ARIA practices page linked above), 'menu's need not be contained in a 'dialog', and also (as noted in the 'aria-dialog-name' link above), 'dialog's must have an 'aria-label', 'aria-labelledby', or 'title', but neither 'DropdownMenu' nor 'ActionMenu' have any kind of header element that could be used for this. Third, if 'Overlay's are 'none', they can’t be focusable (as noted in the 'presentation-role-conflict' link above), but one of our hooks (maybe 'FocusTrap', maybe 'FocusZone') was setting 'tabIndex' to '0' (in the test component), because it did not contain a focusable child. This PR adds a focusable button child so the 'none' 'Overlay' container won’t receive 'tabIndex' '0'. * fix: Resolve lint errors Co-authored-by: Clay Miller <clay@smockle.com> * Generate prop documentation (#1323) * Add new filesystem source * Add component metadata type * Create Props component * Update props table * Handle empty and error states * Add required label * Update required prop styles * Clean up code comments * Remove filesystem plugin * Remove extra markdown file * Add component comment Co-authored-by: Clay Miller <clay@smockle.com> * Improve treeshaking by setting package.json sideEffects (#1332) * fix: mark sideEffects free * fix: update sideEffects delcaration in package.json to improve treeshaking * fix: update sideEffects delcaration in package.json to improve treeshaking * fix: BaseStyles doesnt use sideeffects * chore: add changeset * Update Box documentation * Update BoxProps * Update Box docs * Update Box props * Remove AvatarStack story * Update .changeset/green-worms-nail.md Co-authored-by: Cole Bemis <colebemis@github.com> Co-authored-by: Clay Miller <clay@smockle.com> Co-authored-by: Dusty Greif <dgreif@users.noreply.github.com> Co-authored-by: Matthew Costabile <mattcosta7@github.com>

colebemis added 3 commits June 22, 2021 09:46

Add new filesystem source

ba7bd04

Add component metadata type

0373544

Create Props component

74b299c

colebemis marked this pull request as draft June 24, 2021 19:18

Update props table

a1c48f5

vercel bot temporarily deployed to Preview June 24, 2021 20:00 Inactive

colebemis added 4 commits June 25, 2021 07:35

Handle empty and error states

19a8957

Add required label

2e4381c

Update required prop styles

798f091

Clean up code comments

e8a10cb

vercel bot temporarily deployed to Preview June 25, 2021 16:42 Inactive

colebemis added 2 commits June 25, 2021 09:45

Remove filesystem plugin

0b68b8c

Remove extra markdown file

aacbed0

vercel bot temporarily deployed to Preview June 25, 2021 16:59 Inactive

Add component comment

365c902

vercel bot temporarily deployed to Preview June 25, 2021 17:07 Inactive

Merge branch 'main' into docgen

2c346b0

colebemis marked this pull request as ready for review June 25, 2021 17:33

vercel bot temporarily deployed to Preview June 25, 2021 17:33 Inactive

smockle reviewed Jul 1, 2021

View reviewed changes

smockle approved these changes Jul 1, 2021

View reviewed changes

Merge branch 'main' into docgen

b2a1355

vercel bot temporarily deployed to Preview July 1, 2021 15:43 Inactive

colebemis merged commit b7a1964 into main Jul 2, 2021

colebemis deleted the docgen branch July 2, 2021 14:48

colebemis mentioned this pull request Aug 16, 2021

Generate prop documentation #1109

Closed

1 task

colebemis mentioned this pull request Sep 9, 2021

Missing generated prop documentation for TextInput #1419

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate prop documentation #1323

Generate prop documentation #1323

colebemis commented Jun 24, 2021 •

edited

Loading

changeset-bot bot commented Jun 24, 2021 •

edited

Loading

vercel bot commented Jun 24, 2021 •

edited

Loading

smockle Jul 1, 2021

smockle Jul 1, 2021 •

edited

Loading

smockle Jul 1, 2021

smockle Jul 1, 2021

smockle Jul 1, 2021

colebemis Jul 2, 2021

smockle Jul 1, 2021

smockle Jul 1, 2021

smockle left a comment

Generate prop documentation #1323

Generate prop documentation #1323

Conversation

colebemis commented Jun 24, 2021 • edited Loading

Problem

Solution

Example

.mdx file

Output

Next steps

changeset-bot bot commented Jun 24, 2021 • edited Loading

⚠️ No Changeset found

vercel bot commented Jun 24, 2021 • edited Loading

smockle Jul 1, 2021

Choose a reason for hiding this comment

smockle Jul 1, 2021 • edited Loading

Choose a reason for hiding this comment

smockle Jul 1, 2021

Choose a reason for hiding this comment

smockle Jul 1, 2021

Choose a reason for hiding this comment

smockle Jul 1, 2021

Choose a reason for hiding this comment

colebemis Jul 2, 2021

Choose a reason for hiding this comment

smockle Jul 1, 2021

Choose a reason for hiding this comment

smockle Jul 1, 2021

Choose a reason for hiding this comment

smockle left a comment

Choose a reason for hiding this comment

colebemis commented Jun 24, 2021 •

edited

Loading

`.mdx` file

changeset-bot bot commented Jun 24, 2021 •

edited

Loading

vercel bot commented Jun 24, 2021 •

edited

Loading

smockle Jul 1, 2021 •

edited

Loading