Documentation based on propTypes

[pekala]

It would be nice to display auto-generated component API documentation based on the propTypes and optional comments. I have a partial implementation of this using https://github.com/reactjs/react-docgen and their markdown example. I can prepare a pull request if you think this is a good idea.

[ovidiuch]

Cool. I think this is in line with the project mission, since good interfaces play a bit role in componitization.

But before rushing into a PR, let's talk about the implementation a bit. E.g. where in the code will you extract the info and where would it be the best way to display it in the UI.

PS. I did a small UI refresh to the header+buttons yesterday, get the latest and see if it's sharper than before :-)

[pekala]

In my sketch implementation I had a separate script that I ran before playground that generated Markdown files next to components. Then in cosmos I would load these md files with a markdown-loader, pass the markup for each component to component-playground and render it in a container (a copy of the editor container).
But this is not the optimal way to do it. I suppose the docs generation should done be runtime by cosmos (so that when you update comments/propTypes the docs hot-reload) and without creating actual docs files. It would be really cool, although maybe too far fetched, to have the docs and editor somehow integrated, so that when you edit props you know what are the valid values. Another option is to just display the docs in another sidebar in the playground.

[ovidiuch]

I think it should be another panel, hidden by default, with a discrete button somewhere.

A bit offtopic, but you could also generate random fixtures from propTypes, akin to factories. That would be pretty cool as well as I'm sure writing fixtures is a drag for people who discover Cosmos.

[pekala]

We could integrate something like https://github.com/marak/Faker.js/ to generate these fixtures. Based on comment annotation, property type and property name we could make an educated guess on what makes sense to put in there. What do you think?

[pekala]

For example, we could set a convention that if you annotate your propTypes like this:

propTypes: {
    /**
     * Description of prop "color".
     * faker:internet.color
     */
    color: React.PropTypes.string,
    /**
     * Description of prop "desc"
     * faker:lorem.sentence
     */
    desc: React.PropTypes.string
},

you get a nice random fixture every time.

[ovidiuch]

For example, we could set a convention that if you annotate your propTypes like this:

Cool idea!

Faker looks pretty powerful.

We could add a 2nd executable like node_modules/.bin/generate-fixtures in Cosmos. It would be nice to have the faker: annotation optional, and be able to use some Faker generics based on prop type.