First, there's the issue of documenting the code.
A brief survey of existing documentation generating libraries yielded almost nothing worthwhile. The leaders seem to be Dox (which uses JSDoc syntax that I find pretty unappealing) and Docco (which doesn't have any syntax and as far as I can tell simply puts your comments next to your code in HTML...).
I'm almost tempted to just write my own...
Then there's the issue of documenting the APIs.
There's Swagger, which seems a bit intrusive, since it actual gets all up in your code. But it does seem to also be able to generate docs from JSON schema specs. We should look into it. There's also I/O Docs. Their example page is pretty ugly though, so I dunno if I wanna go there.
I wonder if we should just write a quick little program that parses a JSON schema and renders it in a Markdown or HTML template. I like the idea of having schemas so that we can test against them as well.
First, there's the issue of documenting the code.
A brief survey of existing documentation generating libraries yielded almost nothing worthwhile. The leaders seem to be Dox (which uses JSDoc syntax that I find pretty unappealing) and Docco (which doesn't have any syntax and as far as I can tell simply puts your comments next to your code in HTML...).
I'm almost tempted to just write my own...
Then there's the issue of documenting the APIs.
There's Swagger, which seems a bit intrusive, since it actual gets all up in your code. But it does seem to also be able to generate docs from JSON schema specs. We should look into it. There's also I/O Docs. Their example page is pretty ugly though, so I dunno if I wanna go there.
I wonder if we should just write a quick little program that parses a JSON schema and renders it in a Markdown or HTML template. I like the idea of having schemas so that we can test against them as well.