Research: Explore automatically generating stories from docs-json build output

[jcfranco]

Background

To improve our storybook workflow, docs-json.json could help create stories since it includes metadata for all components.

Desired Outcome

Have a script that creates stories for all components from docs-json.json.

[jcfranco]

Started looking into this and based on the info from docs-json.json we can:

• associate type-matching knobs per attribute
• use usage.md files to create individual stories

There are two key missing pieces affecting automating stories:

• knowing which knobs to show for each story from usage examples. We have some stories that exclude or hardcode attributes based the use case.
• configuring knobs with range of allowed values (see 2nd item from Docs: Enhance auto-generated documentation content #2241 (comment) description)

@caripizza @driskull Do you have any suggestions on what we could do for this? Any sort of file requiring manual edits defeats the purpose, IMO.

[driskull]

For the range issue, I think we can avoid interfaces for now until the bug is fixed.

knowing which knobs to show for each story from usage examples. We have some stories that exclude or hardcode attributes based the use case.

The only way I can think of doing this is with another JSON (basic.md.json?) file where we can specify which knobs should be excluded for the usage example. Then we could access that data using custom docs generation. https://stenciljs.com/docs/docs-custom and build the storybook files?

Unless we can have some kind of markdown comment or code where we can specify that information and strip it out?

[driskull]

If we just need to specify knobs per component, then maybe custom jsdoc tags could work? https://stenciljs.com/docs/docs-json#custom-jsdocs-tags

[jcfranco]

For the range issue, I think we can avoid interfaces for now until the bug is fixed.

Inlining would certainly help. I also forgot to mention that default values coming from a module would also need to be inlined. I know it's small, but I'd rather avoid doing so since we do use that pattern often. I'll see if I can do this w/o explicitly inlining interfaces/types/default values.

The only way I can think of doing this is with another JSON (basic.md.json?) file where we can specify which knobs should be excluded for the usage example.

I like the idea of having special markers in the usage files. It would keep knob info close to the story source.

[driskull]

I like the idea of having special markers in the usage files. It would keep knob info close to the story source.

Yeah, we can have a HTML comment that won't be rendered with some kind of parsable formatting.