Components: Add dedicated doc site with live examples

[ItsJonQ]

Screencast (Features/Walkthrough)

https://www.loom.com/share/4d254c6efc2d4496b95624834256469e

Deploy Preview

https://q-wordpress-component-doc-site-test.netlify.com

(Powered by Netlify)

Details

This PR was in response to my initial RFC/feature suggestion here:
#16953

🚨 Note: This project is very experimental and is a work in progress! 🚨

How this project is generated, and components like the custom Gutenberg blocks, are forks from a work-in-progress doc site generation project by @itsjonq. The plan is to abstract the tooling and components and make those publicly available as easy to use npm packages.

Getting Started

Once you've cloned down @wordpress/gutenberg onto your machine, install the project's dependencies by running:

npm install --prefix ./component-docs

Once the dependencies are downloaded, you can start up the docs local dev environment by running:

npm run docs:component-start

The local dev environment will be viewable at http://localhost:4700/.

How it Works

Generating Data

A handful of scripts look for README.md files located in the /packages/components/ directory. These files then run through a transformer to generate data that's consumable .json by the React app. These .json files are generated into the project's /public directory, allowing for the App to make serverless fetch requests for the .json files.

The idea behind this approach was to open the possibility of saving/serving the data from a REST API endpoint (e.g. a WordPress instance) in the future, if required.

During this process, additional data files are generated such as the package.json and Navigation data that the React app will use in it's UI. Since the React app will need immediate access to this data, the .json files are generated into a special /component-docs/src/data/ directory.

Development

This project uses Create React App, which supports developer experience nicities like live reloading and linting.

Live Component Examples

Live component examples can be rendered from the README.md files by wrapping examples with a special wp:docs tag:

<!-- wp:docs/sandbox { "name": "button" } -->
...
<!-- /wp:docs/sandbox -->

The React app uses custom Gutenberg blocks that transform that data. In the above example, the code snippet renders a live preview/editor, powered by React Live.

Build (Deploy)

This project can be built by running the following command:

npm run docs:component-build

Once completed, the built files can be found under component-docs/build.

The built files is a static site (or web app). The directory can be deployed onto any server or service that can render HTML.

[gziolo]

I was AFK for more than a week so I probably missed some discussions about this PR. What's the exact plan for integration with the existing WordPress infrastructure? As of today, you can browse all those components here:
https://developer.wordpress.org/block-editor/components/

or an individual component:
https://developer.wordpress.org/block-editor/components/autocomplete/

It seems like this should be integrated together or replaced. I don't know to be honest but just letting you know that it's maintained in a different repository. @chrisvanpatten and @nosolosw should know more.

Aside: code in component-docs is using different tooling and workflows than the rest of the codebase in Gutenberg repository. It might create some friction for contributors who would like to help with maintenance or its further development.

[gziolo]

Great work obviously, I should start with that. I really like the part which uses HTML comments to discover code examples and treat them as blocks :)

[griffbrad]

@gziolo My hope is that we can work out a good path for merging this local component playground-like experience. Once that is in place, we can pretty easily use the same components to integrate with the Handbook. I wrote up a proof of concept for that here:

#16953 (comment)

[ItsJonQ]

Aside: code in component-docs is using different tooling and workflows than the rest of the codebase in Gutenberg repository. It might create some friction...

@gziolo We can definitely make adjustments to make it more approachable. The way I set this up was just one way to go about it 😊

[gziolo]

This is all really exciting, thanks for sharing your comments :) I'm looking forward to having all of this integrated.

@griffbrad - have you played with MDX? This looks familiar but for WP components embedded in blocks :)

[ItsJonQ]

MDX is really neat! Typically, it's associated with some sort of build system (e.g. Webpack). Which may limit integration with something like WordPress integration.

A potential solution may be this?
https://mdxjs.com/advanced/runtime

(I'm not an MDX expert!)

@griffbrad and I paired a lot on various markdown -> component parsing ideas. Leveraging the WP block parser seemed to be the most flexible way to go

[gziolo]

Now that we landed Storybook in #17475, this can be closed. Let's work towards adding more examples to the Storybook which can be accessed at https://wordpress.github.io/gutenberg/design-system/components/.

Thank you for all the efforts exploring the approached proposed in this PR 💯

[ItsJonQ]

@gziolo My pleasure! Thank you, @epiqueras, and everyone for getting Storybook in! 🎉