Generate docs using JSDoc (or something).

[jordwalke]

We've tried to be consistent about documenting the React core using markdown style comments, and JSDoc style annotations, so it would be easy to create a utility that auto-generates documentation pages for the core itself. Ideally this would only rely on node.js/npm and not Java.

Using the "good first bug" label, but we should rename that label to "good first contribution".

[zpao]

Every once in a while I use http://yui.github.io/yuidoc/ (which is basically javadoc). It's node-based and seems to be the best option.

However we run into a bunch of issues. This would require a pass through the code to make sure we have the right syntax everywhere. This is on my eventually list, but haven't had the time to go through everything. We basically need somebody to step up and do what's being done in https://github.com/emberjs/ember.js/pull/3082

If anybody is interested, let me know!

[hojberg]

I can jump on this. I'm familiar with yuidoc.

[vjeux]

Someone tweeted about docsets http://kapeli.com/docsets

https://twitter.com/kapeli/status/401461544468635648

[Kapeli]

@vjeux I don't see how my tweet is related to this.

[vjeux]

@Kapeli: We haven't yet agreed on any form of documentation and docsets looks like a good target. So I mentioned it here in case someone wants to try and integrate React with it.

[Kapeli]

Just in case there's a misunderstanding: please note that a docset is just a way to package the documentation which you already have into something that is searchable by Dash or Zeal. Docsets are not a way of generating documentation from source files, which I think is what this issue is about.

[chenglou]

Happy Dash user here. Love the app. Will be generating React docs for it soon so that we can all have an offline, instantly fuzzy-searchable React documentation =).

[ericchaves]

Hey, @chenglou did you manage to write a react docset?

[chenglou]

I did a rough version and passed it over to @agirton (hope that's the same one as on #reactjs!).

[agirton]

@chenglou I am! I have it working well. Just need to go through all the pages and get the anchor links hooked up so there are items in lower left hand table TableView for easier navigation. I've been busy so haven't been able to do that feature just yet.

[joelburget]

@chenglou @agirton any chance you can point me to your docsets? Not fully working is fine.

[chenglou]

@agirton ping on this ^

[quantizor]

If you're using Markdown comments, then Docco is a very good choice because you won't have to change anything! http://jashkenas.github.io/docco/

[zpao]

Docco doesn't actually generate API docs AFAIK, just an html page with your code and comments all together.

[quantizor]

That's correct - it takes the philosophy that the code should be mostly self-explanatory with obvious variable naming, and the markdown comments give additional context. You can write variable definitions, etc if you want to though.

[quantizor]

See backbone or underscore's annotated sources for examples. I prefer the style. http://underscorejs.org/docs/underscore.html

[zgotsch]

Did we ever track down those docsets?

[zpao]

@3lux I don't think annotated source is the most helpful thing that could be done. We have a pretty good set of comments in the code. Right now our public API is small while we have a lot of other code that makes it all work. Backbone and Underscore have all their code in 1 file, are smaller and expose a lot of their code as public APIs.

[iautom8things]

Is there any update on a docset for use with Dash?

[chenglou]

@agirton @mazubieta it's ready. I'll put up something tomorrow.

Edit: React docset is now in dash!

[joelburget]

Thanks @chenglou !

[iautom8things]

Awesome, thank you!

[InSuperposition]

How about a lib that uses Facebook's fork of Esprima or parts of Flow(?) to analyze the JS and JSX Abstract Syntax Trees, then generate a documentation data structure and optionally transform source files. I looked around but had no luck with finding a similar existing library.

The next step would be create a collection of React components (react-doc?) to provide the documentation views.

• React docs would updated by static code analysis, not annotations, less prone to human error
• Auto generate JSX supported HTML/SVG elements and attributes (0.12.2 documentation is currently out of date)
• Auto generate docs for user created React components (Mixins, Property types and defaults, etc..)
• The "react-doc" components could be a tutorial on building React components while interacting with the documentation
• Optionally prepend annotations for other documentation libs (JSDoc, YUIDoc or plugin...)

[zpao]

I was actually just thinking of a Flow-based documentation tool. Unfortunately none exist AFAIK and there's still some need for the JSDoc comment (at least for the description, and other @class, etc things JSDoc does).

Side note... 0.12.2 documentation shouldn't be out of date, I updated it myself :) But let me know what's missing and I'll followup.

I think the idea of a react-doc tool is certainly interesting. We actually have something we do internally at FB that does some of what you're talking about, pulling out at least some of the PropTypes and handling inheritance. It's tied to some specific ways we write out components but it would be cool to generalize it so it could be open sourced. That's pretty tangential to this specific issue, but cc @fkling anyway :)

[revolunet]

What do you guys would use to create react components documentation with the API from comment and a live example ?

[fkling]

@revolunet: FWIW, I'm currently working on open sourcing the tool that we use internally. Regarding examples, I don't think there will be a good automatic solution. Those components for which examples will be useful likely need more complex examples as well (children, event handlers, etc).

Overall I think it would be great if we could establish some guidelines around how to write a React component and how to provide examples for it.

[hzoo]

@fkling yeah I think some guidelines could be helpful - angular has some styleguides that talk about ideas for syntax, conventions, and structure - ex: https://github.com/johnpapa/angularjs-styleguide

[zpao]

Eh, after this long using human maintained docs, I think we'll just continue down that path. It's not without problems, but with a small surface area, I don't think we actually need autogenned docs.

[yordis]

@jordwalke @zpao About JSDoc I don't think JSDoc is a solution (for now) It doesn't like JSX and most of the time we will code in JSX. Check this https://github.com/jsdoc3/jsdoc/issues/1001

@revolunet Check it out https://github.com/React-UI/generator-react-ui-component. You have a good environment setup. It's using YUIdoc because JSDoc doesn't support JSX right now but YUIdoc doesn't like it too much alternative tags and in react, for example, we have states and YUIdoc doesn't have a state tag, yet.

[revolunet]

thanks @yordis will check it out

[mik01aj]

https://github.com/sapegin/react-styleguidist looks pretty impressive, too!