joyent/node — Issue #2684: JSON API docs
Author: isaacs
Created: 2012-02-03 02:11:42+00:00
State: open

Goal: Match the API reference to jquery's format, so that it can be consumed for intellisense/autocomplete in various editors that already support jquery.

1. Separate out API reference from more conceptual stuff. This work is started already by Garen at Cloud9.
2. Parse the API docs into a format like http://api.jquery.com/jsonp/

This means that every API method/section/etc needs to have argument type information added.

Further constraint: We can't deviate from markdown. It's just too nice, and very good for encouraging patches, rendering as HTML easily, etc.

Goal: every url like .../docs/latest/api/fs.html should have a .../docs/latest/api/fs.json which is the JSON representation.

Instead of converting the markdown to HTML, we should convert the markdown to JSON, and then shove it through some kind of template engine thingie (Jade? ejs? Custom HTML with `@FIELD@` markers? What are the cool kids using these days?)

(A nice next step would be to do the same for internal web pages, and have `make doc` make the whole thing using a single template, but that might be over-reaching. Start with API docs.)