search

canonical / react-components

A set of components based on Vanilla Framework
https://canonical.github.io/react-components
95 stars 51 forks source link

Migrate to CSF stories with autodocs #1001

Closed petermakowski closed 6 months ago

petermakowski commented 9 months ago

I'd suggest we adopt the latest storybook CSF format with autodocs as used in maas-react-components react-components.

It'll help avoid issues with story rendering in the future.

rsmelo92 commented 8 months ago

Hello, I've created a PR for a first change, if accepted I will migrate all the others

bartaz commented 7 months ago

While reviewing the proposed PR I started looking a bit into storybook docs, and TBH I don't fully understand why would we need to migrate to CSF, or does it actually replace MDX?

It seems the MDX is still fully supported and recommended as a way to control the structure of the documentation: https://storybook.js.org/docs/writing-docs/mdx

rsmelo92 commented 7 months ago

@bartaz It's seems that since storybook 7.0, MDX is taking a heavy hit in favor of CSF+autodocs

Not only on the CSF page they say that CSF is now the recommended way of writing stories, but they are deprecating the way this repo is writing stories (Component.stories.mdx) in favor of a CSF file holding the main logic together with a MDX that references it (as seen here and here)

I don't have the inner context you guys have, but if this repo really needs mdx, we can run the migration script that storybook has, migrate to latest storybook version, write CSF files and reference them on each mdx to keep using them as they are RN. (Or we can pin storybook version and keep as it is)

But if we consider that mdx is not mandatory here, its better to migrate the stories to CSF and be future proof, even allowing the migration to storybook8 to be smoother later. In my humble opinion this is the best scenario!

Bonus: here are some discussions regarding this

bartaz commented 7 months ago

Thanks for more context @rsmelo92, I really appreciate this.

So, as far as I understand now, we've been using MDX for writing stories (and a bit of docs on top). Stories part is now deprecated in favour of CSF. As for the custom docs MDX is still an option, but the question is if it's needed at all. And the answer is probably not. The only bits of "docs" that we have are couple paragraphs of text here and there. Which clearly can be handled by CSF and JSDoc (I guess it's just a pity that JSDoc doesn't seem to support markdown and everything ends up in single paragraph?).

Overall, I'm convinced that we should continue. Thanks.

github-actions[bot] commented 5 months ago

:tada: This issue has been resolved in version 0.50.6 :tada:

The release is available on:

Your semantic-release bot :package::rocket: