Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Surface Sub-component Readmes in Handbook Documentation #15107

Open
mkaz opened this issue Apr 22, 2019 · 2 comments
Open

Surface Sub-component Readmes in Handbook Documentation #15107

mkaz opened this issue Apr 22, 2019 · 2 comments
Labels
[Tool] Docgen /packages/docgen [Type] Developer Documentation Documentation for developers [Type] Enhancement A suggestion for improvement.

Comments

@mkaz
Copy link
Member

mkaz commented Apr 22, 2019

Numerous sub-components have readme and documentation created, but these are not surfaced in the Gutenberg Handbook, and thus can not easily be linked to.

One example is InnerBlocks, the component documentation is here:
https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inner-blocks

But the Gutenberg Handbook documentation for Block Editor shows as it is undocumented here: https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/

Which also means we can't link to it from places like here, which tries but is a broken link
https://wordpress.org/gutenberg/handbook/designers-developers/developers/block-api/block-templates/

@mkaz mkaz added the [Type] Developer Documentation Documentation for developers label Apr 22, 2019
@aduth
Copy link
Member

aduth commented Apr 25, 2019

Considering action steps here:

  • Unless I'm mistaken, the process of including the document should be as simple as adding to manifest.json and re-running npm run docs:build
  • There is already a "Components" top-level section in the handbook. Currently, these map directly to UI components offered by the @wordpress/components module. Would it be fine to include components from other modules (block-editor) as well, or does that risk confusion? Alternatively, could this be listed under the @wordpress/block-editor heading, or do we risk confusion on (a) having a very deep hierarchy and (b) fragmentation of components documentation.
  • I'm assuming there's some "magic" behind the scenes to remap a link from /packages/block-editor/src/components/inner-blocks/README.md to an equivalent location in the handbook, and that this would automatically take effect to fix the "Block Templates" documentation once reachable.

@bph
Copy link
Contributor

bph commented Dec 16, 2023

Now that the Developer Resources redesign has been put into production, this would be the next step to provide a complete and comprehensive documentation for developers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Tool] Docgen /packages/docgen [Type] Developer Documentation Documentation for developers [Type] Enhancement A suggestion for improvement.
Projects
None yet
Development

No branches or pull requests

5 participants