Gutenberg: Update API docs for packages automatically

[nosolosw]

This issue tracks the necessary work to create a command that regenerates the API documentation upon Public API changes.

By adding some code to the top-level README file of a package they get automatically updated. See instructions. There are some packages that may be more involved or need work in the tool that generates the docs (docgen), in which case they have some notes added.

Progress:

Misc:

• [x] Reuse in npm run docs:build https://github.com/WordPress/gutenberg/pull/14216
• [x] Update handbook core-data section to use docgen. https://github.com/WordPress/gutenberg/pull/15421

Packages:

• [x] a11y https://github.com/WordPress/gutenberg/pull/14288
• [x] annotations. No Public API.
• [ ] api-fetch. Needs some sort of @class/@memberof support to auto-document methods, etc. See also token-list. https://github.com/WordPress/gutenberg/issues/15178
• [x] autop https://github.com/WordPress/gutenberg/pull/14287
• [x] babel-plugin-import-jsx-pragma. CommonJS module (out of scope).
• [x] babel-plugin-makepot. CommonJS module (out of scope)
• [x] babel-preset-default. CommonJS module (out of scope)
• [x] base-styles. CommonJS module (out of scope)
• [x] blob https://github.com/WordPress/gutenberg/pull/14286
• [x] block-directory. No public API.
• [ ] block-editor & editor. Many undocumented components, some are exported through compose. To be considered after edit-post docs are merged, so we can extrapolate what we learned there.
• [x] block-editor https://github.com/WordPress/gutenberg/pull/14285
• [x] block-library https://github.com/WordPress/gutenberg/pull/14282
• [x] block-serialization-default-parser https://github.com/WordPress/gutenberg/pull/14280
• [x] block-serialization-spec-parser. CommonJS module (out of scope)
• [x] blocks https://github.com/WordPress/gutenberg/pull/14279
• [x] browserslist-config. CommonJS module (out of scope)
• [ ] components. Most components are undocumented.
• [x] compose https://github.com/WordPress/gutenberg/pull/14278
• [x] core-data. No Public API.
• [x] create-block. CommonJS module (out of scope)
• [x] custom-templated-path-webpack-plugin. CommonJS module (out of scope)
• [x] data https://github.com/WordPress/gutenberg/pull/14277
• [x] data-controls.
• [x] date https://github.com/WordPress/gutenberg/pull/14276
• [x] dependency-extraction-webpack-plugin. CommonJS module (out of scope)
• [x] deprecated https://github.com/WordPress/gutenberg/pull/14275
• [x] docgen. CommonJS module (out of scope)
• [x] dom https://github.com/WordPress/gutenberg/pull/14273
• [x] dom-ready https://github.com/WordPress/gutenberg/pull/14272
• [x] e2e-test-utils.
• [x] e2e-tests. No Public API. Tests to be executed by Jest.
• [ ] edit-navigation.
• [x] edit-post https://github.com/WordPress/gutenberg/pull/14271
• [ ] edit-site.
• [ ] edit-widgets.
• [ ] editor.
• [x] element https://github.com/WordPress/gutenberg/pull/14269
• [x] env. Not support (CLI tool).
• [x] escape-html https://github.com/WordPress/gutenberg/pull/14268
• [x] eslint-plugin. CommonJS module (out of scope)
• [x] format-library. No Public API.
• [ ] hooks. Exports are created dynamically. Could they benefit from using the @name tag?
• [x] html-entities https://github.com/WordPress/gutenberg/pull/14267
• [x] i18n https://github.com/WordPress/gutenberg/pull/14266
• [x] icons. No need to document their public API.
• [ ] interface.
• [x] is-shallow-equal. CommonJS module (out of scope).
• [x] jest-console. No Public API, adds Jest matcher.
• [x] jest-preset-default. CommonJS module (out of scope)
• [x] jest-puppeteer-axe. No Public API, adds a new Jest matcher.
• [x] keyboard-shortcuts.
• [x] keycodes https://github.com/WordPress/gutenberg/pull/14265
• [x] library-export-default-webpack-plugin. Not supported (CommonJS module).
• [x] list-reusable-blocks. No Public API.
• [ ] media-utils.
• [x] notices. No Public API.
• [x] npm-package-json-lint-config. Not supported (CommonJS module).
• [ ] nux. React component exported through compose. Complex README.
• [x] plugins https://github.com/WordPress/gutenberg/pull/14263
• [x] postcss-themes. CommonJS module (out of scope).
• [x] prettier-config. CommonJS module (out of scope)
• [ ] primitives.
• [x] priority-queue https://github.com/WordPress/gutenberg/pull/14262
• [x] project-management-automation. No public API.
• [x] redux-routine https://github.com/WordPress/gutenberg/pull/14228
• [x] rich-text https://github.com/WordPress/gutenberg/pull/14220
• [x] scripts. CommonJS module (out of scope).
• [ ] server-side-render. Exported through withSelect.
• [x] shortcode https://github.com/WordPress/gutenberg/pull/14218
• [ ] token-list. Needs some sort of @class/@memberof support to auto-document methods, etc. See also api-fetch.
• [x] url https://github.com/WordPress/gutenberg/pull/14217
• [x] viewport https://github.com/WordPress/gutenberg/pull/14214
• [x] warning.
• [x] wordcount https://github.com/WordPress/gutenberg/pull/14213

[gziolo]

Not supported (CommonJS module).

In the majority of cases, there is nothing to auto-generate for CLI based modules so I wouldn't consider it as an issue :)

[nosolosw]

For those subscribed to this master issue: most packages are ready for review.

[nosolosw]

Only 4 reviews left! Props to @mkaz for crushing them all.

[gziolo]

plugins merged and wordcount is ready to go. This leaves data and edit-post. I hope to review the latter on Monday if @mkaz doesn't beat me to it :)

[gziolo]

@nosolosw - I don't think it's a good candidate for Good First Issue in the current form :)
Should we close this issue and open follow-up issues for the remaining work?

[nosolosw]

Agree to remove the "Good first issue". I still think it has value as a _master issue_, otherwise, things will become too scattered and will be difficult to understand where things stand.

[nosolosw]

Some thoughts about how to deal with current "undocumented symbols" that may or may not have a README file:

• a minimal approach for those that have a README file: add a @see tag to the README file (not @link, though). Note that we should use an URL to GitHub, so it's reachable from other places where this is published (handbook, npm).
• add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

cc @aduth

[aduth]

• add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

By "include", do you mean _output to_ in a similar way to the demarcations present in the top-level README files?

[aduth]

• add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

By "include", do you mean _output to_ in a similar way to the demarcations present in the top-level README files?

To answer my own question, I assume that yes, it would be simple enough to add additional entry points for each of the components to output to their respective README.md files. I think the main challenge we'll face here is how to properly document Component classes in such a way which provides useful information; specifically prop types. There may be overlap with #15178, treating prop types as arguments to the constructor. It may be the sort of thing we'd want a "custom formatter" for as well.

[aduth]

• a minimal approach for those that have a README file: add a @see tag to the README file (not @link, though). Note that we should use an URL to GitHub, so it's reachable from other places where this is published (handbook, npm).

Related: #15107

Edit: Pull request at #15194

[nosolosw]

There's https://github.com/WordPress/gutenberg/pull/15421 to teach the handbook to use docgen for doc generation.

[nosolosw]

Updated the list of packages. There's some new ones that are easy wins, in case anyone is interested.