Skip to content
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
Closed

Documentation generator for users #152

addyosmani opened this issue Jul 16, 2012 · 11 comments
Labels
Milestone

Comments

@addyosmani
Copy link
Member

@addyosmani 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
Copy link
Member Author

@addyosmani addyosmani commented Jul 18, 2012

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

@sindresorhus
Copy link
Member

@sindresorhus 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
Copy link
Member Author

@addyosmani 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
Copy link
Member

@robdodson 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
Copy link
Member

@sindresorhus 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
Copy link
Member

@robdodson robdodson commented Sep 17, 2012

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

@pahlers
Copy link

@pahlers 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
Copy link
Contributor

@sleeper 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
Copy link

@creativeaura creativeaura commented Oct 26, 2012

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

@paulirish
Copy link
Member

@paulirish paulirish commented Nov 14, 2012

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

@georgschlenkhoff
Copy link

@georgschlenkhoff georgschlenkhoff commented Dec 31, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants
You can’t perform that action at this time.