[docs] Autogenerate the property description for the AppBar

[oliviertassinari]

@subjectix Are you ok with this way? It's like what react-native is doing https://github.com/facebook/react-native/blob/master/Libraries/Components/SwitchIOS/SwitchIOS.ios.js#L46.

[alitaheri]

@oliviertassinari I think we should provide some meta data for our tooling to better render the final html. First we must use Markdown, second we could add some @ tags (depending on tooling) to provide automation hooks. But for now it's awesome. just consider using markdown where ever needed.

[oliviertassinari]

What's the markdown feature for?
I plan to use https://github.com/reactjs/react-docgen.

[oliviertassinari]

But yes, we could convert the output to markdown with https://github.com/reactjs/react-docgen/blob/master/example/generateMarkdown.js and then to HTML with #2226

[alitaheri]

I plan to use https://github.com/reactjs/react-docgen.

Good decision.

What's the markdown feature for?

For code examples, acceptable value tables, etc...

[oliviertassinari]

code examples

I don't think that code examples should be in the description.
For this, I plan to create separe component. We could then use each example component for three use case:
-testing
-demonstration
-code description

acceptable value tables

This will be extracted from the source code

[alitaheri]

@oliviertassinari Well you make some good points. Alright, I'm ok with this. 👍 👍

[oliviertassinari]

@subjectix @shaurya947 I think that I'm done for this first iteration. Here is the result:

The doc build fails, I'm waiting benjamn/recast#238 to be released.

[alitaheri]

@oliviertassinari Good job 👍 Is there anyway to move the example and description to the source code too? Something like, jsdoc on the class deceleration?

[oliviertassinari]

I'm done. @subjectix can you review?

That the new look of the documentation page https://github.com/oliviertassinari/material-ui/blob/doc-autogenerated/docs/src/app/components/pages/components/app-bar.jsx.

[alitaheri]

😱 Give me some time 😄

[oliviertassinari]

/lib is missing, I don't know how to make it work.

[alitaheri]

try running npm run build -- --watch on the root of the project to see if it helps.

can't webpack map paths?

[alitaheri]

I can't get it to work:

Webpack outputs this:

ERROR in ./~/recast/main.js
Module not found: Error: Cannot resolve module 'fs'

[oliviertassinari]

I need benjamn/recast#238 to be released.

[alitaheri]

Nevermind I cloned into the recast repo. It's fixed for now.

[alitaheri]

Ok I saw how it turned out. There are 2 major issues,

1. material-ui/lib/... must be fixed somehow.
2. props should be categorized, structured and be more readable. right now it's hard to distinguish each prop.

and some other prettier patterns:

1. lambda doesn't need explicit return.
2. AppBarExampleIconButton better be a class, the external function may confuse people.

P.S. stop rebasing, I can't track changes >.>

[oliviertassinari]

1. I can't agree more!
2. I'm following react-native style (http://facebook.github.io/react-native/docs/mapview.html#content)
   How would you improve it?
3. I guess I should use React.createClass for the examples.

stop rebasing, I can't track changes

Sorry

[alitaheri]

IMO a table can be more pleasing to the eye. like how react-bootstrap does it. I mean even reading the props from react-native hurts my eyes 😢

If you want to keep it this way at least make the names bold. use mono-space for type and defaults, and put more space between each prop.

asides from these, really awesome job 👍 👍 👍

[oliviertassinari]

IMO a table can be more pleasing to the eye

Let's try it.

[oliviertassinari]

That's better 👍

[alitaheri]

@oliviertassinari It's beautiful. Great job 👍 👍 👍

[alitaheri]

@oliviertassinari I think it's better to annotate only the required props and oit all the optional annotations. isn't that better? since only so few are required.

[frankf-cgn]

@oliviertassinari You letting generate markdown within the PropTypeDescription is pretty awesome - nice work! 👍
After renaming from "Description" to "PropTypeDescription" was it intentional to let the const remain to "Description" (src/app/components/PropTypeDescription.jsx#L19)?

[oliviertassinari]

After renaming from "Description" to "PropTypeDescription" was it intentional to let the const remain to "Description"

Oups, thanks for finding this.

[oliviertassinari]

I have taken into account your feedbacks.

[alitaheri]

Should this be here? I mean... shouln't it be where this file is read from?

[oliviertassinari]

I don't get it. What do you mean?

[alitaheri]

Examples is inside the readme file, that means every read me MUST end with ###Examples. shouldn't it be where you make the final markdown FROM this readme file and append this there? also maybe the title should be there too.

[alitaheri]

I think the best practice would be to add a HeaderSection component that takes a title and a description markdown text and renders the header section. just like the PropTypeDescription,

[alitaheri]

@oliviertassinari Also, can you please use markdown in props description too? use ` for references and codes.
Very awesome job 👍 👍

[alitaheri]

This too maybe?

[frankf-cgn]

@subjectix Don't you think that gets too specialized? I can easily reason about the component <PropTypeDescription>. It takes burden from the developer because the doc gets autogenerated. Awesome. But by introducing another component like <HeaderSection> we are definetly going to build an abstraction onto an abstraction.
Let's return more to kiss instead of throwing lot's of components onto this.
@oliviertassinari Just an rough idea: Maybe it is possible to inject the html the component <CodeExample> generates into <MarkdownElement>?

[alitaheri]

@frankf-cgn you have a point, but that ###Example should go away don't you think?

[frankf-cgn]

@subjectix Indeed you have a point, too. The need to have a heading of a following component in the markdown-file makes it though to understand it. So maybe the idea with injecting the <CodeExample> into the <MarkdownElements>might be a solution, maybe @oliviertassinari has a better idea.
Let me sleep about this.

[alitaheri]

@frankf-cgn I like you idea. have a good night 💤

[oliviertassinari]

we are definetly going to build an abstraction onto an abstraction.

I think that the best abstraction for the doc is the markdown format.
Having say that, I can't see any good way to improve the current solution.

[frankf-cgn]

Sadly, my "injecting"-idea does not work. That's because <CodeExample> not only renders html but the working component, too. And that is really cool, because the doc and the example literally share the same code!
Compared to the documentation effort of other projects, what @oliviertassinari created with the help of <PropTypeDescription> and the restructuring of the documentation-folder layout is more advanced, powerfull and easy to approach.

So my 2 cents: Lets go ahead with this PR.
@oliviertassinari: Do you need any help on this? Do you want to switch the whole documentation to the new system at once within this PR? If we instead go on with one [Doc Enhamcement]-PR per component we can share the work ;-)

[oliviertassinari]

So my 2 cents: Lets go ahead with this PR

🎉

I want to merge this PR first, but I need benjamn/recast#238 to be release 😒. Or to find a way to fix it here.

Do you need any help on this.

I think that we should migrate component per component. So yes 👍.

[frankf-cgn]

@oliviertassinari Did you like this styling more than the default gfm-table?
If yes, I will invest some time to make it work.

[alitaheri]

@frankf-cgn Lovely 👍

[oliviertassinari]

@frankf-cgn Their is still room for improvement 👍.
I have added a temporarty fix for recast. I'm gonna merge this.

@subjectix @frankf-cgn Thanks for your help 🎉.

[alitaheri]

Awesome 👍 🎉 🎉
Thanks for doing this @oliviertassinari

[shaurya947]

👍 great initiative @oliviertassinari @subjectix

[frankf-cgn]

@oliviertassinari Really nice work and awesome idea to let the props-table beeing autogenerated!

[newoga]

Just noticed this, this is awesome! 👍