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

Docs: Update link for Inner Blocks #14941

Merged
merged 2 commits into from
Apr 12, 2019
Merged

Docs: Update link for Inner Blocks #14941

merged 2 commits into from
Apr 12, 2019

Conversation

mkaz
Copy link
Member

@mkaz mkaz commented Apr 12, 2019

Description

The Inner Blocks component is linked to the wrong spot, the old link is going to /packages/editor/src/components/inner-block/README.md the new location should be block-editor package.

This PR updates the link on block-registration, and block-templtes page.

However, I don't think the actually Inner Block documentation is being published anywhere.

@nosolosw if I look in the source repo on Github, the readme file is there for Inner Blocks.
See: https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inner-blocks

However, if I look at the Gutenberg Handbook, it looks empty here
https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

Types of changes

Documentation

Copy link
Member

@jorgefilipecosta jorgefilipecosta left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

@@ -486,7 +486,7 @@ transforms: {

* **Type:** `Array`

Blocks are able to be inserted into blocks that use [`InnerBlocks`](/packages/editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.
Blocks are able to be inserted into blocks that use [`InnerBlocks`](/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmm, it looks like we have a bunch of links pointing to the wrong URLs. We should either:

  1. Use full URLs for files that aren't published to the handbook (all component's READMEs, things that live within */src/*, etc.): https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

  2. Use relative URLs to the handbook docs: /docs/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

@oandregal
Copy link
Member

However, I don't think the actually Inner Block documentation is being published anywhere.

Yup, it's not. To my knowledge, it was never published to the handbook. Note that https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks uses the info from the JSDoc comments (in this case there is none).

Here are some thoughts on how we could improve this:

  • most components aren't documented (as in: they have JSDoc comments).
  • many components do have a README file.

What if we moved the relevant info from the component's README to JSDoc comments, then automatically fill both the component's README and the handbook page? This is one of the tasks I'm tracking on #14227 At the moment the ./bin/update-readmes only updates the packages' README, but we could adapt it to also update the inner component's READMEs.

@mkaz
Copy link
Member Author

mkaz commented Apr 12, 2019

Ok, I'll merge this one which "fixes" the link at least to the right packages section.

We can track the sub-components on your at #14227 - I need to dig in a little more to understand completely. My initial hunch is that it is probably best to try and match the handbook docs to Github directory structure as much as possible.

The /packages/ relative URL does get transform to work when viewing the handbook, but not sure if the links work properly in the npm and github contexts of viewing documentation. A quick search and it looks like 20 or so spots are linking this way.

@mkaz mkaz merged commit 992b330 into master Apr 12, 2019
@mkaz mkaz deleted the docs/fix/inner-block-links branch April 12, 2019 13:23
mchowning pushed a commit to mchowning/gutenberg that referenced this pull request Apr 15, 2019
* Update link for Inner Blocks, component of block-editor package

* Add back whitespace in title, fixed in different PR
@youknowriad youknowriad added this to the 5.5 (Gutenberg) milestone Apr 15, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants