Add current work in progress of readme.md and api.md

[victorb]

This is my current WIP of having a better readme and also added the API docs.

Missing currently:

• Examples of all the calls
• Better description of how to use the methods
• Probably update the TOC
• Check links et al
• Proofread

At first, tried to automatically generate the documentation with a script combining the output of go-ipfs and reading the method fingerprint from js-ipfs-api but got a bit stuck and think I tried to overengineer a solution for something that would be simpler to fix manually.

Related to #58

Was #102 before but moved branch upstream.

[RichardLitt]

• List options for each call. (Hope, not a commitment).

[daviddias]

@victorbjelkholm @RichardLitt @dignifiedquire Can I get an update on this? What is blocking us from finishing the documentation? Is there a decision between using manual vs generated docs from mocha (#105) ?

[dignifiedquire]

Looking into jsdoc@3 currently. Looks really good so far as I think auto generated docs are much better than manual kept ones as they just tend too much to get out of sync with the code but the test docs generator doesn't give any abilities to do good customizations

[daviddias]

As discussed on the last sprint meeting, we are going with https://github.com/ipfs/js-ipfs-api/pull/105/files which offers really good documentation compared to the inexistent that we have now, and eventually, we will have better docs for IPFS API itself. Closing this one for now :)

[RichardLitt]

Thanks @diasdavid and @victorbjelkholm