Use API Blueprint for documentation and include aglio generation

[ArthurHoaro]

I've rewritten the API doc using the API Blueprint specification, including @nodiscc proposition from #1.

I've also added the aglio HTML generation for more readability.
Note that the HTML generation is a piece of cake, and could easily be added in the makefile later:

npm install -g aglio
aglio -i api-documentation.md -o api-documentation.html

Any feedback appreciated.

[virtualtam]

Is it possible to automate HTML generation and hosting? This could be as simple as creating a GH Pages project site for the API and switching to a gh-pages branch on this repo.

[ArthurHoaro]

I never used GH pages, but Travis supports NodeJS, so I guess it is possible.

[virtualtam]

Yup, this way we can:

• push Markdown API docs to master
• let Travis generate the static HTML and push it to gh-pages
• profit!

[kalvn]

I didn't know this API Blueprint + aglio process but it looks good.

I already used RAML + raml2html generators but I don't know which one can be considered as the most "standard".

[ArthurHoaro]

I've used swagger which looks similar (YAML syntax). However, I was looking for something based on Markdown, to be coherent with Shaarli's documentation.