Documentation generator for users

[addyosmani]

A potential user today asked if Yeoman plans on supporting a documentation generator such as Docco.

I'm not sure whether or not this is a little too much to try squeezing in for the first version, but I found the below and thought we could at least discuss whether we want to give people a docs generator of some sort.

https://github.com/DavidSouther/grunt-docco

[addyosmani]

Just discussed this with @paulirish. Looks like we might explore using Grunt + jsDoc.

[sindresorhus]

jsDoc is good, but it requires Java and Rhino...

jsDuck also looks good. It uses Esprima (which is awesome) and has a Ruby dependency.

There is a jsDoc Node.js port on NPM, but it's not actively maintained...
I also found a ticket on jsDoc about porting it to Node, but there hasn't been done any work there.

If we want a Node.js based doc generator, which we should, there are:

• YUIdoc - generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen
• Dox - JavaScript documentation generator for node using markdown and jsdoc

I think we should use Dox. It is popular. Created by the awesome TJ Holowaychuk. And it let's users decide how to show their documentation. It also supports jsDoc tags.

What do you think?

[addyosmani]

Thanks for the comprehensive research, Sindre :)

I think Dox looks hot. If we do go for a doc generator, I'd be happy for us to use it.

[robdodson]

The downside to Dox, if I recall, is that it just generates a blob of JSON. It's up to the user to write their own view which consumes that JSON. Maybe you guys know of a good tool to use for displaying it all?

[sindresorhus]

@robdodson Lot's of Dox generators out there. Maybe this one: https://github.com/cbou/markdox

We'll do a thorough research before deciding on anything.

Let us know if you have any suggestions ;)

[robdodson]

Oh nice! I was looking for something like this a while back. Very cool :D

[pahlers]

I would vote for Docco + something like jsDoc or jsDuck . I think Docco is a nice way to view and learn to understand someones code. But it's not a nice way to surf through the API, then jsDoc/jsDuck is a better solution.

[sleeper]

Same as @eonlepapillon : Docco is really great for code walkthrough ... For API documentation, jsDuck or Dox (the dependency on Ruby for jsDuck is not that ennoying I guess, if we consider that compass already has a ruby dependency ...)

[creativeaura]

I will vote for jsDuck, I have used it for many projects very generates nice interactive docs.

[paulirish]

closing this but we documented this for users at https://github.com/yeoman/yeoman/wiki/Additional-FAQ

[georgschlenkhoff]

check out https://github.com/kengz/dokker