Automate block documentation based on block.json data

[oandregal]

There's a fair bit of automated documentation we generate based on code at the moment: packages, data, components, etc.

With more blocks supporting the block.json specification and more features being ported to it, it is a high-quality source from which we can extract a lot of information easily:

• block name
• block category
• block attributes
• style attributes

For a start, one thing we could do would be to create a new top-level section called "Block Reference" that would list them all with their main data.

[oandregal]

cc @mkaz @annezazu

[oandregal]

#24421 could have benefited from having an automated tool for this as well.

[JustinyAhin]

Hi @nosolosw @mkaz @gziolo

I'd like to tackle this issue.

But I have a couple of questions/things I need to know.

I guess right now, there is no documentation that is generated based on JSON?

Also, from this conversation, I'm seeing that espree (https://github.com/eslint/espree) could be a good tool for doing such automation. Where could I start using it? I've been looking at its documentation and was a bit lost about whether or not it takes files as entry instead of JSON code directly.

If you know uses cases of that and can point me to them, that would be awesome.

Thanks :)

[oandregal]

Nice!

I'm not aware of anything we generate from JSON that goes into the block editor handbook. I'm not sure either what use cases were I thinking back then but there doesn't seem to be a need for espree in this case ― processing a JSON from a node script should be enough. We have a few in https://github.com/WordPress/gutenberg/tree/master/bin/api-docs in case that gives you a place to start poking around.

Have you looked at this other comment below? Looking at ways to integrate #24152 into the block editor handbook would be cool.

[oandregal]

I've used a script I've pushed to the add/block-json-extractor branch to list the block supports in a way that's useful to prepare the dev notes.

Hopefully, that could be taken forward to embed that info in some part of the block editor handbook.

[oandregal]

In this space, there's also this project by Riad that would be great to integrate into the block editor handbook.

[mkaz]

Closed in #36183