New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation generator for users #152

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

Comments

Projects
None yet
8 participants
@addyosmani
Member

addyosmani commented Jul 16, 2012

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

This comment has been minimized.

Show comment
Hide comment
@addyosmani

addyosmani Jul 18, 2012

Member

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

Member

addyosmani commented Jul 18, 2012

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

@sindresorhus

This comment has been minimized.

Show comment
Hide comment
@sindresorhus

sindresorhus Jul 18, 2012

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?

Member

sindresorhus commented Jul 18, 2012

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

This comment has been minimized.

Show comment
Hide comment
@addyosmani

addyosmani Jul 18, 2012

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.

Member

addyosmani commented Jul 18, 2012

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

This comment has been minimized.

Show comment
Hide comment
@robdodson

robdodson Sep 16, 2012

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?

Member

robdodson commented Sep 16, 2012

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

This comment has been minimized.

Show comment
Hide comment
@sindresorhus

sindresorhus Sep 17, 2012

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 ;)

Member

sindresorhus commented Sep 17, 2012

@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

This comment has been minimized.

Show comment
Hide comment
@robdodson

robdodson Sep 17, 2012

Member

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

Member

robdodson commented Sep 17, 2012

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

@pahlers

This comment has been minimized.

Show comment
Hide comment
@pahlers

pahlers Oct 26, 2012

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.

pahlers commented Oct 26, 2012

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

This comment has been minimized.

Show comment
Hide comment
@sleeper

sleeper Oct 26, 2012

Contributor

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 ...)

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

This comment has been minimized.

Show comment
Hide comment
@creativeaura

creativeaura Oct 26, 2012

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

creativeaura commented Oct 26, 2012

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

@paulirish

This comment has been minimized.

Show comment
Hide comment
@paulirish

paulirish Nov 14, 2012

Member

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

Member

paulirish commented Nov 14, 2012

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

@georgschlenkhoff

This comment has been minimized.

Show comment
Hide comment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment