Codesandbox stories

[benallfree]

Ok so yeah this could be pretty awesome. It would require some codegen for the packages (see examples/.template), but nothing too bad. Any time we updated stories we would just re-run the codegen.

A few notes:

• Lots of codegen duplication required to make individual packages for each story
• Stories are copied into the packages verbatim. Ie, the example packages flow from the stories
• style.css needs to be copied into each package root due to ../../style.css in each story - ideas?
• Good news! Codesandbox does pull from the repo every time - and as soon as the user edits anything, it converts to a stand-alone sandbox. Perfect. Our links are always in sync.

Try https://codesandbox.io/s/github/benallfree/react-babylonjs/tree/codesandbox-stories/examples/babylon-basic

[brianzinn]

looks slick. ok, so you are saying codegen to push/copy the storybook story to app.js for each example? that looks doable.

[benallfree]

I think that's going to be the best way. But if the story imports anything storybook-specific such as addon decorators, then we'll need to separate out the bare component for importing into the example packages. Yet another reason not to use Storybook's built-in GUI for tweaking state :)

[benallfree]

PS, I would imagine that the codgen could be a storybook postbuild step

[benallfree]

Oh and a couple unrelated questions:

• Have you considered making this repo use yarn workspaces? I think then you could import react-babylonjs directly into storybook rather than specifying those paths in main.js
• Have you considered migrating the stories to Typescript?
• What code formatting are you using? If you haven't done anything, prettier and a lint pass would be a good choice

[brianzinn]

I kept JavaScript just to make it easier for non-Typescript people to setup a playground, but it would be better switched over. If I’m not using prettier, but it can be added to eslint and would be a good addition.

I’m ok with yarn workspaces - it may end up with multiple react instances. Would need to experiment.

to be honest I’m really open to redo everything and even abandon storybook for a better learning experience. Storybook is a constant source of problems to maintain.

[benallfree]

What about a kitchen sink example project and a gitbook (or something else) that embeds different paths? Storybook is nice because it includes the code but I do agree it's more for component testing and less for documentation. How is Babylon doing their docs?

[brianzinn]

their api docs are generated through typedoc, while their main docs site is manually built.

[benallfree]

Ok let me play with a couple ideas in this branch 👍

[benallfree]

Ok I added a gatsbyjs static site to replace storybook... Try this:

cd static
yarn
yarn start

Then browse to http://localhost:8000/ and http://localhost:8000/basic/1-initializing.

[brianzinn]

🤯 WOW - this is exactly what I imagined that I wanted. Another great benefit is it will be easy for people to contribute to the documentation! This will be a great way to walk through explanations - can explain how the <box /> is built and show constructor parameters, etc. I am completely ready to switch - really like this a lot. Will be able to make everything much clearer - really like the MDX as well. Let me know when you are done and I will merge. One thing I need to work out is the github workflow to deploy on commit for storybook - I will disable that now.

[benallfree]

Ok I think the dust has settled. Check it out now:

• We are using https://github.com/kevin940726/remark-codesandbox which can beam mdx code sections over to Codesandbox and even embed them via iframe
• We have a custom template in static/codesandbox-template which is used every time. This is amazing because it means sandboxes launched from our docs will always use the latest template
• Writing new samples is EASY. Just launch an existing demo and alter App.tsx to suit. Copy/paste into the mdx files. If you have to add package deps, copy the new package.json from Codesandbox into our template and every sample will get updated

Now before we commit to gatsby, I should mention that remark-codesandbox works equally well in Storybook. Scroll down to the Demo section at the bottom: https://reaviz.io/?path=/docs/docs-chart-types-area-chart--page. Here's the source for that page https://raw.githubusercontent.com/reaviz/reaviz/master/docs/charts/AreaChart.story.mdx. They're using mdx as well, so maybe Storybook is fine?

They are using the identical strategy: a custom codesandbox template and code samples embedded in the docs.

Something to think about before we go migrating everything away from storybook :D

[brianzinn]

I like what you have done much more than storybook!! I feel like it's going to be much easier to customize and tweak - especially with regards to how you have made custom content ie: a helpful tutorial to guide through from imperative Component to declarative re-use. I want to share some recipes and tips where people tend to get stuck and it will be much easier in this format.

I'm really excited with what you have already built. I think most of the examples in storybook can be made to be part of a samples section and it will be easier to organize how you have done. It's already much better than what is currently there. I want to work on extending the API documentation with links to babylonjs docs.

As soon as you are ready to hand-off I can port over more docs/samples. Thanks for all your efforts here.

[benallfree]

I think it's ready. I went through a lot of approaches to get here, so I feel pretty sure this is a good way forward 😅

Merge when ready!

[brianzinn]

yay! merged. i am super busy today, after that I will work on getting it up on the github pages! thanks again - great work. are you OK if I put you up on the contributors section of main readme?

[benallfree]

Of course, thank you!