style guide generation, react-styleguidist integration? #602

jurgob · 2016-11-03T13:30:48Z

Hi, is it possible to generate a style guide from the stories?
something like react-styleguidest (https://github.com/sapegin/react-styleguidist) do?
Does it make sense to write something from scratch? or maybe it make more sense to do some tools to "generate" the react-styleguidist files?

In my project I was using both react-styleguidest and react-storybook, so I wrote a storybook generator from the styleguidest examples. (here the code: https://gist.github.com/jurgob/58f6f46c34e991dc449effe5731dd693).

Maybe doing the opposite (from stories to markup files) it could be the fastest way?

Let me know what do you think

jurgob · 2016-11-03T15:02:38Z

probably a static building could solve my problems, but as far as I can see, it miss 3 feat witch are present in react-styleguidist:

on-the-fly code editor.
markdown description for every story
markdownd pages included in the generated styleguide (same format of github)

cdaringe · 2016-11-04T21:34:07Z

can the addons not fill this role somehow already?

jurgob · 2016-11-04T22:01:48Z

mmm, not sure. Btw have a longer description for the story could be a good idea?

arunoda · 2016-11-05T01:44:14Z

Hey, we have some solutions in Storybook land for this. Let me show you them:

Info addon: https://github.com/storybooks/react-storybook-addon-info
Readme Addon: https://github.com/tuchk4/storybook-readme
Our react-docgen integration

sapegin · 2017-01-13T07:53:05Z

Hey, React Styleguidist author is here ;-) Is anyone still interested in Storybooks and React Styleguidist integration?

ghost · 2017-01-13T22:43:25Z

I might be yes :)

jbovenschen · 2017-02-20T11:08:31Z

@sapegin I'm interested in the integration with styleguidist, also I'm happy to help or make the integration, happy to hear of your still interested.

sapegin · 2017-02-21T08:35:54Z

@jbovenschen Hi Jaco! I’m not very familiar how Storybook works but probably we could somehow convert stories to Styleguidist Markdown format. Probably it will require some changes in Styleguidist itself. I’m happy to discuss it ;-)

logankoester · 2017-02-22T21:38:01Z

I'm still interested in this as well, definitely!

cdaringe · 2017-02-23T00:09:32Z

I will definitely follow commits on such a thing. very interested!

cdaringe · 2017-02-24T21:57:32Z

one idea is a styleguidist loader.

in that regard, storybook doesn't even need awareness of styleguidist. you just:

.add('widget', require('styleguidist!./my-widget.md'))

the loader would return the root react Component for the styleguide and blamo, we're on our way!

@sapegin, thoughts?

jbovenschen · 2017-02-27T19:04:03Z

Currently I try to work out something where you get a link, like "Open isolated ->" in the examples generated by styleguidist.

@cdaringe Will the webpack example return the complete set of styleguidist stories? Or create new ones based on it's content, if so is it not better to create some kind of addon?

cdaringe · 2017-02-28T21:05:04Z

@jbovenschen, it would load only the content as defined by ./my-widget.md, so just the one styleguidist story, or set of stories defined therein. loading a full build probably wouldnt provide much value, IMHO

sapegin · 2017-02-28T21:33:56Z

Then what’s the difference with running Styleguidist separately if you still have to write docs in Styleguidist format?

cdaringe · 2017-02-28T22:18:47Z

Then what’s the difference with running Styleguidist separately if you still have to write docs in Styleguidist format?

great point, i dont know what i was thinking. my head's on straight now! perhaps a better approach would be an addon, providing a styleguidist wrapper thingy™:

import { styleguidist } from 'storybook-styleguidist'
import Button from './path/to/button'
.add('Button', styleguidist(
  Button,  // tells which props to inject into addon pane
  () => { /* story 1 */ }, // renders normal styleguidist experience
  () => { /* story 2 */ }
)

maybe not ideal, because in that approach, all stories share the same viewer. instead...

import { styleguidist } from 'storybook-styleguidist'
import Button from './path/to/button'
.add(styleguidist(
  Button,
  'story1', () => { /* story 1 */ },
  'story2', () => { /* story 2 */ }
)

^^ would load the props documentation into the story1 & story2 "styleguidist" addon panes, & the stories would be laid out per the below in the storybook:

├── Button
│   ├── story1
│   ├── story2

usulpro · 2017-03-02T15:32:23Z

Hey! I like an idea to integrate them such a way that it could be possible to use Strorybook as a development tool and Styleguidist as a customizable static output.

I was looking for ways to seamlessly transfer stories data to styleguidist and now I can show the example how it's possible to create markdown from storybooks via addon.

storiesOf('Usual story', module)
    .addStyleGuide('Simple Example', () => (
      <div className="example-component">
        <Button title={text('Subtitle3', 'Knob1.SubTitle')} />
      </div>
    ), { getCode: storeCode })

It's possible to pass additional description to each story like in react-storybook-addon-info (actually it's a fork). And markdown could be devided by stories or any other way.

The big pros is that it's possible to use with other addons like Knobs. e.g. set all knobs and then generate a markdown with stored prop values. (I hope it'll be possible to support decorators as well)

Here're demo and repo

In this demo you can see markdown in the addon panel after selecting single story or do it automatically to generate all of them.
it's just an outline for now. I think if it's usefull it's possible to reduce excessive code and have something realy simple for usage and avoid .addStyleGuide (keep it only if we want to add some additional docs to the description, in all other cases - just usual .add)

@sapegin @cdaringe @jbovenschen @jurgob do you have any ideas is it possible to continue and how to pass this markdown (and everything else) to Styleguidist?

One of the problems could be is that do it in browser not server (now the most simple way is just save a file manually) or could we generate styleguide on a client side?

So I'll be happy if it could help with this work :)

sapegin · 2017-03-02T15:42:38Z

@usulpro That’s amazing! Exactly what I was thinking (but had no idea how to implement it ;–)

how to pass this markdown (and everything else) to Styleguidist?

That’s a good question. Generating real files is not the best way. But I don’t really know how can we connect Storybook and Styleguidist. Does Storybook have some API? Is it possible to have all Markdown snippets in Node?

usulpro · 2017-03-03T12:35:58Z

Storybook has API for addons developing.

But maybe we can use this #435 ?

Asking to have Markdown snippets in Node do you mean to use this API? I'm confused that it needs to require everything from this Markdown as well.

sapegin · 2017-03-09T13:48:08Z

I should study Storybook API, right now I don’t understand how to connect two tools together ;-)

pke · 2017-03-14T08:57:26Z

I also always wondered what the difference between storybooks and styleguidist is. I think I favour the latter for its easy markdown readme and most of all, users of the guide can "write their own story", because styleguidist allows live editing of code from the (static) guide side.

sapegin · 2017-05-08T15:57:32Z

@pke Yeah, ability to generate a style guide with all components on the same page and different way of writing stories / examples are the main differences.

stale · 2017-10-31T08:19:48Z

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. We do try to do some housekeeping every once in a while so inactive issues will get closed after 90 days. Thanks!

stale · 2017-11-02T09:05:34Z

Hey there, it's me again! I am going to help our maintainers close this issue so they can focus on development efforts instead. If the issue mentioned is still a concern, please open a new ticket and mention this old one. Cheers and thanks for using Storybook!

IanVS · 2018-11-05T13:54:26Z

This issue fits really well with this article comparing storybook and styleguidist: https://blog.hichroma.com/storybook-vs-styleguidist-2bd93d6dcc06. The TL;DR is that they both fill different needs. Storybook is great for developers creating components in isolation, and styleguidist is well-suited for creating documentation around them. The author ends by saying he he wishes the two could be combined. I agree.

To accomplish this, I think we need two pieces. One is to be able to create rich documentation about a component, and https://github.com/tuchk4/storybook-readme seems perfect for that. But the piece that is still missing, I think, is being able to generate a single page with all of the documentation for all of the components. Imagine a new developer on the team looking for a particular type of component, but not knowing what it's called. It is much easier to scroll through a single page looking for something that looks right, than it is to click through the elements in a sidebar, guessing from their names.

All that to say, does anyone think it might be possible to create a single page combining all of the stories together, using either info-addon or storybook-readme?

pke · 2018-11-05T15:11:12Z

I don't want to learn a new DSL for writing documentation. I still think styleguidist solves the problem at hand better and smoother.
Also by facilitating readme files in every component folder, that readme can be seen when browsing the github repo without even opening the styleguidist docu. So I can not see how both projects fill different needs, for me they do the same.

IanVS · 2018-11-05T15:36:24Z

I agree that being able to pull in readme docs into stories with storybook-readme is awesome for the reasons you describe. I think the main thing still missing from storybook, is the ability to scroll down a single page and see all the components, without having to click once or twice through the scrollbar for each one.

crash7 · 2019-01-10T19:05:59Z

I'm trying to build the same, just because I want the view-port feature that storybook has with that addon but couldn't find a way to load the stories from the readme or the other way around.

QingLeiLi · 2019-07-08T09:31:10Z

Any progress about this?

IanVS · 2019-07-08T12:22:18Z

I'm hopeful that this will give us what we are looking for: https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a

QingLeiLi · 2019-07-08T12:41:00Z

I'm hopeful that this will give us what we are looking for: https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a

Thanks for the quick reply, I will take a look at the article. Also thanks for the hard work what you are doing on the SB.

shilman · 2019-07-08T13:13:31Z

@IanVS @QingLeiLi If you want to try it out, here's a more recent guide: https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing

Currently in alpha, hustling to get it into beta this week 🤞

QingLeiLi · 2019-07-08T17:21:55Z

@IanVS @QingLeiLi If you want to try it out, here's a more recent guide: https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing

Currently in alpha, hustling to get it into beta this week 🤞

Nine work! I will give it a try soon.

arunoda added the discussion label Nov 3, 2016

cdaringe mentioned this issue Feb 23, 2017

where shall we document component usage Tripwire/octagon#16

Closed

usulpro mentioned this issue Apr 13, 2017

All stories displayed on a single page (kitchen sink) #760

Closed

ndelangen added the compatibility with other tools label Jul 7, 2017

stale bot added the inactive label Oct 31, 2017

stale bot closed this as completed Nov 2, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

style guide generation, react-styleguidist integration? #602

style guide generation, react-styleguidist integration? #602

jurgob commented Nov 3, 2016

jurgob commented Nov 3, 2016

cdaringe commented Nov 4, 2016

jurgob commented Nov 4, 2016

arunoda commented Nov 5, 2016

sapegin commented Jan 13, 2017

ghost commented Jan 13, 2017

jbovenschen commented Feb 20, 2017

sapegin commented Feb 21, 2017

logankoester commented Feb 22, 2017

cdaringe commented Feb 23, 2017

cdaringe commented Feb 24, 2017 •

edited

Loading

jbovenschen commented Feb 27, 2017

cdaringe commented Feb 28, 2017

sapegin commented Feb 28, 2017

cdaringe commented Feb 28, 2017

usulpro commented Mar 2, 2017

sapegin commented Mar 2, 2017

usulpro commented Mar 3, 2017

sapegin commented Mar 9, 2017

pke commented Mar 14, 2017

sapegin commented May 8, 2017

stale bot commented Oct 31, 2017

stale bot commented Nov 2, 2017

IanVS commented Nov 5, 2018

pke commented Nov 5, 2018

IanVS commented Nov 5, 2018

crash7 commented Jan 10, 2019

QingLeiLi commented Jul 8, 2019

IanVS commented Jul 8, 2019

QingLeiLi commented Jul 8, 2019

shilman commented Jul 8, 2019

QingLeiLi commented Jul 8, 2019

style guide generation, react-styleguidist integration? #602

style guide generation, react-styleguidist integration? #602

Comments

jurgob commented Nov 3, 2016

jurgob commented Nov 3, 2016

cdaringe commented Nov 4, 2016

jurgob commented Nov 4, 2016

arunoda commented Nov 5, 2016

sapegin commented Jan 13, 2017

ghost commented Jan 13, 2017

jbovenschen commented Feb 20, 2017

sapegin commented Feb 21, 2017

logankoester commented Feb 22, 2017

cdaringe commented Feb 23, 2017

cdaringe commented Feb 24, 2017 • edited Loading

jbovenschen commented Feb 27, 2017

cdaringe commented Feb 28, 2017

sapegin commented Feb 28, 2017

cdaringe commented Feb 28, 2017

usulpro commented Mar 2, 2017

sapegin commented Mar 2, 2017

usulpro commented Mar 3, 2017

sapegin commented Mar 9, 2017

pke commented Mar 14, 2017

sapegin commented May 8, 2017

stale bot commented Oct 31, 2017

stale bot commented Nov 2, 2017

IanVS commented Nov 5, 2018

pke commented Nov 5, 2018

IanVS commented Nov 5, 2018

crash7 commented Jan 10, 2019

QingLeiLi commented Jul 8, 2019

IanVS commented Jul 8, 2019

QingLeiLi commented Jul 8, 2019

shilman commented Jul 8, 2019

QingLeiLi commented Jul 8, 2019

cdaringe commented Feb 24, 2017 •

edited

Loading