Update API docs for packages automatically

[oandregal]

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:

• Reuse in npm run docs:build Use a central script instead of one per package to generate docs #14216
• Update handbook core-data section to use docgen. Consolidate doc generation and fix next/prev links issue #15421

Packages:

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

[oandregal]

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?

[oandregal]

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.

[oandregal]

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

[oandregal]

There's #15421 to teach the handbook to use docgen for doc generation.

[oandregal]

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

[DaisyOlsen]

@oandregal are these items still relevant?

[oandregal]

It's been a while since anyone worked on this, so I presume we can safely close it.