I’m the author of a fairly sized (and growing) framework. It primarily exposes JavaScript APIs, but also has public APIs in Ruby and a growing CoffeeScript segment. (CoffeeScript will eventually encompass most of the project, but there will always be a significant pure-JavaScript presence.)
Up until now, I’ve been documenting the JavaScript with PDoc and the Ruby with RDoc. Though I’ve no issues with RDoc, unfortunately PDoc is aging, high-maintenance, and requires a heck of a lot of typing that feels like superfluous clutter. Also, the transition of most of the code to CoffeeScript renders PDoc much less useful than it was.
Example of the project’s current documentation
I’ve experimented with Rocco in a local branch and it works better than I expected. What’s really nice is that it works with all my code, from Ruby to Coffee to JS. It’s nice to see all the documentation in one place. It’s kind of cool to see the source code next to the documentation, too, and this makes it very clear what a particular code segment is actually doing.
However, I am a bit worried about the overall structure. Docco/Rocco seems great for niche projects with very few public APIs, but its read-the-entire-project style strikes me as a double-edged sword. Though it’s very informative, having to vertically scroll through the files without even a table of contents (not to mention, knowing which file to go to in the first place!) seems like it would make it difficult to actually find anything. Also, the default template required some hacking because the list of files was too long to be displayed. Not a huge deal but an annoyance, and a hint that this project may be out of Rocco’s league.
I’m now considering CoffeeDoc. Judging just by the example, it seems promising, but it is of course Coffee-centric, which brings me back to running 3 separate documentation tools: RDoc, CoffeeDoc and — what? JSDoc?
I’m not completely adverse to running separate tools for the separate sources, but it becomes hard to reconcile that into a coherent result that doesn’t feel like 3 separate Web sites.
So I guess my question is: what tool do you use or suggest? What language(s) does it support? Is it easy to browse, read, and actually find a needle in the haystack that is your project? I’m even considering rolling my own tool at this point, except that I can’t believe no one else has encountered a problem like this (and I don’t really want to waste time if I don’t have to).
Sphinx directly supports javascript. Documentation of Ruby and CoffeeScript is supported through extensions (https://bitbucket.org/birkenfeld/sphinx-contrib/).
From the website:
The following features are present, work fine and can be seen “in action” in the Python docs: