Migrate API documentation into Apiary format (API Blueprint)

[ronaldtse]

Migrate from Wiki to here. For @abunashir and @ribose-jeffreylau . Thanks!

• [x] #3 Log in & log out
• [x] #4 Spaces
• [ ] #5 Connections
• [ ] #6 Settings
• [x] #7 App Data
• [x] #8 Invitation
• [x] #9 File
• [x] #10 Calendar

[ribose-jeffreylau]

You can familiarize yourself with the new format with the API Blueprint tutorial.

[skalee]

@ribose-jeffreylau @ronaldtse How about adding some CI tool which validates documentation?

[ribose-jeffreylau]

@skalee Seconded. What options are there for APIB?

[skalee]

Actually anything can be run in Travis.

There is a plenty of tools listed on API Blueprint pages. I've already tried few of them for my development purposes, but had much trouble with running most of them. I have strong feeling that most of these tools are outdated, unmaintained, incomplete, or otherwise buggy. However, some options are promising.

Dredd looks really good, but it tests blueprints against remote server, and it may be an overkill in current stage. Specified responses must fully match actual ones, and I don't know how we could make such expectations passing, especially when it comes to requests which modify things on server. I'm afraid that we would have to create a separate API instance with some database fixtures, which are reset after each test. Sounds complicated.

The second option is to use some API Blueprint parser. I mean to run it against blueprints, and to check if the exit status equals 0. That should guarantee at least that blueprints are well-formed. There are some parsers on the tools lists (e.g. Protagonist) but I have no opinion on any.

The third option is to use some HTML documentation renderer, perhaps in the production-like configuration. Then we can kill two birds with one stone: validate documentation (with the exit status check), and upload the most current master branch documentation somewhere.

I haven't spent much time on researching, so I it's difficult to recommend particular tools.

[ribose-jeffreylau]

Thanks @skalee !

It looks like drafter could be a good candidate of an API Blueprint parser. It's built by Apiary themselves.

I like the third option as well.

Snowboard looks promising. It renders its output into both HTML and APIB (adding support for its own style of transclusion), as well as being able to run its own mock server, etc.

docprint also looks simple which is a good thing.

[ronaldtse]

@skalee @ribose-jeffreylau then could we then perhaps have a "drafter" job for Travis CI to ensure that at least the documentation is valid?

[skalee]

Created #33. Self-assigned to me for now, but actually I'm not sure who should do this.