Documentation generator for users #152

Closed
addyosmani opened this Issue Jul 16, 2012 · 10 comments

Projects

None yet

7 participants

@addyosmani
Member

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
Member

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

@sindresorhus
Member

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
Member

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
Member

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
Member

@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
Member

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

@eonlepapillon

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
Contributor
sleeper commented Oct 26, 2012

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
Member

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

@paulirish paulirish closed this Nov 14, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment