[Doc] Autogenerate the property description fo the AppBar #2382

oliviertassinari · 2015-12-05T14:25:26Z

@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 · 2015-12-05T14:31:48Z

@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 · 2015-12-05T14:54:26Z

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

oliviertassinari · 2015-12-05T14:57:09Z

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 · 2015-12-05T15:05:05Z

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 · 2015-12-05T15:14:00Z

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 · 2015-12-05T15:19:25Z

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

oliviertassinari · 2015-12-06T00:29:36Z

@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 · 2015-12-06T05:16:57Z

@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 · 2015-12-06T12:12:46Z

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 · 2015-12-06T12:14:01Z

😱 Give me some time 😄

oliviertassinari · 2015-12-06T12:17:55Z

docs/src/app/components/AppBar/ExampleIconMenu.jsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import AppBar from 'material-ui/app-bar';


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

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

can't webpack map paths?

alitaheri · 2015-12-06T12:30:10Z

I can't get it to work:

Webpack outputs this:

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

oliviertassinari · 2015-12-06T12:39:38Z

I need benjamn/recast#238 to be released.

alitaheri · 2015-12-06T12:45:20Z

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

alitaheri · 2015-12-06T12:59:00Z

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

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

and some other prettier patterns:

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

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

oliviertassinari · 2015-12-06T13:03:51Z

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

stop rebasing, I can't track changes

Sorry

alitaheri · 2015-12-06T13:09:10Z

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 · 2015-12-06T13:22:29Z

IMO a table can be more pleasing to the eye

Let's try it.

oliviertassinari · 2015-12-06T14:09:50Z

That's better 👍

alitaheri · 2015-12-06T14:23:36Z

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

alitaheri · 2015-12-06T14:24:54Z

@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 · 2015-12-06T15:48:33Z

@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 · 2015-12-06T17:31:08Z

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

Oups, thanks for finding this.

oliviertassinari · 2015-12-06T20:42:50Z

I have taken into account your feedbacks.

alitaheri · 2015-12-06T20:52:29Z

docs/src/app/components/AppBar/README.md

+It is used for navigation, search branding, and actions.
+An app bar is also referred to as the primary toolbar or action bar for Android.
+
+### Examples


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

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

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.

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 · 2015-12-06T20:57:25Z

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

alitaheri · 2015-12-06T20:58:23Z

docs/src/app/components/AppBar/README.md

@@ -0,0 +1,7 @@
+## AppBar


This too maybe?

frankf-cgn · 2015-12-06T21:47:15Z

@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 · 2015-12-06T21:49:56Z

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

frankf-cgn · 2015-12-06T21:56:40Z

@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 · 2015-12-06T22:00:05Z

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

oliviertassinari · 2015-12-06T22:08:44Z

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 · 2015-12-07T10:46:16Z

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 · 2015-12-07T10:49:25Z

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 · 2015-12-07T13:48:08Z

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

alitaheri · 2015-12-07T13:54:14Z

@frankf-cgn Lovely 👍

oliviertassinari · 2015-12-07T14:53:07Z

@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 🎉.

[Doc] Autogenerate the property description fo the AppBar

alitaheri · 2015-12-07T15:04:49Z

Awesome 👍 🎉 🎉
Thanks for doing this @oliviertassinari

shaurya947 · 2015-12-07T17:01:53Z

👍 great initiative @oliviertassinari @subjectix

frankf-cgn · 2015-12-08T07:51:07Z

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

newoga · 2015-12-08T08:30:03Z

Just noticed this, this is awesome! 👍

oliviertassinari mentioned this pull request Dec 6, 2015

The Docs #1276

Closed

oliviertassinari added the Review: review-needed label Dec 6, 2015

[Doc] Autogenerate the property description fo the AppBar

bc65bc6

oliviertassinari mentioned this pull request Dec 6, 2015

[Doc Enhancement] Introduce MarkdownElement #2224 #2226

Closed

oliviertassinari reviewed Dec 6, 2015
View reviewed changes

oliviertassinari mentioned this pull request Dec 6, 2015

Include 'import' code block for Popovers, per convention. #2325

Closed

[Doc Enhancement] Introduce MarkdownElement #2224

857300e

alitaheri reviewed Dec 6, 2015
View reviewed changes

docs/src/app/components/AppBar/README.md

@@ -0,0 +1,7 @@

## AppBar

Copy link

Member

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This too maybe?

[Doc] Temporary fix for recast

6a5fb2f

oliviertassinari added a commit that referenced this pull request Dec 7, 2015

Merge pull request #2382 from oliviertassinari/doc-autogenerated

718c840

[Doc] Autogenerate the property description fo the AppBar

oliviertassinari merged commit 718c840 into mui:master Dec 7, 2015

oliviertassinari deleted the doc-autogenerated branch December 7, 2015 15:04

oliviertassinari mentioned this pull request Dec 7, 2015

[Doc] Convert Avatar to use the new standard #2407

Merged

oliviertassinari mentioned this pull request Dec 8, 2015

Migration of the documentation #2433

Closed

29 tasks

oliviertassinari mentioned this pull request Jan 11, 2016

AppBar demo is out of date or bug #1992

Closed

alitaheri removed the PR: Needs Review label Feb 15, 2016

snyk-bot mentioned this pull request May 6, 2020

[Snyk] Upgrade webpack-dev-server from 3.1.14 to 3.10.3 hzhz/material-ui#5

Open

zannager added docs Improvements or additions to the documentation component: app bar This is the name of the generic UI component, not the React module! labels Mar 14, 2023

		@@ -0,0 +1,31 @@
		import React from 'react';
		import AppBar from 'material-ui/app-bar';

[Doc] Autogenerate the property description fo the AppBar #2382

[Doc] Autogenerate the property description fo the AppBar #2382

Conversation

oliviertassinari commented Dec 5, 2015

alitaheri commented Dec 5, 2015

oliviertassinari commented Dec 5, 2015

oliviertassinari commented Dec 5, 2015

alitaheri commented Dec 5, 2015

oliviertassinari commented Dec 5, 2015

alitaheri commented Dec 5, 2015

oliviertassinari commented Dec 6, 2015

alitaheri commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

alitaheri commented Dec 6, 2015

oliviertassinari Dec 6, 2015

Choose a reason for hiding this comment

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

alitaheri commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

alitaheri commented Dec 6, 2015

alitaheri commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

alitaheri commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

alitaheri commented Dec 6, 2015

alitaheri commented Dec 6, 2015

frankf-cgn commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

oliviertassinari Dec 6, 2015

Choose a reason for hiding this comment

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

alitaheri commented Dec 6, 2015

alitaheri Dec 6, 2015

Choose a reason for hiding this comment

frankf-cgn commented Dec 6, 2015

alitaheri commented Dec 6, 2015

frankf-cgn commented Dec 6, 2015

alitaheri commented Dec 6, 2015

oliviertassinari commented Dec 6, 2015

frankf-cgn commented Dec 7, 2015

oliviertassinari commented Dec 7, 2015

frankf-cgn commented Dec 7, 2015

alitaheri commented Dec 7, 2015

oliviertassinari commented Dec 7, 2015

alitaheri commented Dec 7, 2015

shaurya947 commented Dec 7, 2015

frankf-cgn commented Dec 8, 2015

newoga commented Dec 8, 2015