[TO BE UPDATED] Keeping the API documentation up-to-date

Owned by Cesar Tonnoir (Unlicensed)
Last updated: Jun 18, 2017
1 min read

For Impac! API documentation, we have a dedicated branch: https://github.com/maestrano/impac/tree/gh-pages

This branch contains only one html file with all the API doc. This file is accessible using the Github Pages: http://maestrano.github.io/impac/

The html file is generated from a .md file available here (branch develop): https://github.com/maestrano/impac/blob/develop/doc/v1/index.md and using the API blueprint (https://apiblueprint.org/) + aglio tool (https://github.com/danielgtaylor/aglio).

So basically the process is: 
1. create new branch from #develop
2. update index.md
3. generate index.html using aglio
4. merge your branch to #develop and #master
5. commit the generated file to #gh-pages

Every time a new widget engine is created, we have to update this doc with the following information:

  • provide a short description of the widget engine
  • describe the required and optional parameters (required: metadata[organization_ids], engine... / optional: hist_parameters...)
  • provide a JSON response example

If a widget is using a metadata that is not described in the beginning of the doc and that is shared between several widgets (http://maestrano.github.io/impac/#all-widgets-metadata), this part has to be updated as well.

I recommend to use a .md previewer for the edition, such as: http://dillinger.io/. A API Blueprint previewer plugin is also available for Atom: https://atom.io/packages/api-blueprint-preview.