Re:Designing Great API Docs
by typicalrunt on Wednesday January 11, 2012 @06:12PM
(#3454158)
What tools are out there to generate an HTML doc of your api? I don't necessarily need it to parse my code, but I want to take the busy-work out of coding HTML.
[ Parent
| on HN ]
A bit out of date but I have used rapi-doc in the past: https://github.com/sabman/rapi_doc for some of our internal API reference docs, for quickly reminding ourselves of the current state of our API's. It's for Ruby on Rails though, so if you are familiar with RoR, it will parse your controllers looking for API related comments for each controller action. Here's an example https://beta.spacialdb.com/apidoc/layers.html But I am sure there are better tools out there, I'd be keen to learn about them.
Re:Designing Great API Docs
by twakefield on Wednesday January 11, 2012 @06:35PM
(#3454235)
We used sphinx (http://sphinx.pocoo.org/). Uses reStructedText and you can pull in comments/samples directly from your code to help make sure everything's up to date.
It's in a very early stage (not production ready), but some colleagues and I have been working on a automated testing DSL built on top of RSpec that lets you generate API documentation from tests which validate the documentation is correct. It requires RSpec and a Rack-compatible service (incl. Rails). I think the idea has legs.
I like ROBOdoc [1]. It's not well known enough IMO, but it has the huge advantage to work with about any language you can think of, which is a real boon for mixed codebases (for instance C + Python + HTML + Javascript or any other combination you can think of). Of course it can be used to generate HTML, PDF, man pages, POD or about anything else.