Merge pull request #268 from ipfs/feature/152-add-readme-sections

Added Contribute, License, and Banner

API.md

@@ -2,10 +2,8 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
-- [API](#api)
-  - [Callbacks and promises](#callbacks-and-promises)
-  - [Reference](#reference)
-    - [Core](#core)
+- [API Reference](#api-reference)
+  - [Core](#core)
       - [`version([callback])`](#versioncallback)
       - [`id([callback])`](#idcallback)
       - [`block`](#block)
@@ -32,7 +30,7 @@
         - [`pin.list(hash, options, [callback])`](#pinlisthash-options-callback)
       - [`log`](#log)
         - [`log.tail([callback])`](#logtailcallback)
-    - [Extensions](#extensions)
+  - [Extensions](#extensions)
       - [`add(arrayOrBufferOrStream, [callback])`](#addarrayorbufferorstream-callback)
       - [`name`](#name)
         - [`name.publish(hash, [callback])`](#namepublishhash-callback)
@@ -47,7 +45,7 @@
         - [`files.write(file, bufferOrArray, [options, callback])`](#fileswritefile-bufferorarray-options-callback)
         - [`files.mv(src, target, [callback])`](#filesmvsrc-target-callback)
       - [`mount(ipfs, ipns, [callback])`](#mountipfs-ipns-callback)
-    - [Tooling](#tooling)
+  - [Tooling](#tooling)
       - [`commands([callback])`](#commandscallback)
       - [`update`](#update)
         - [`update.apply([callback])`](#updateapplycallback)
@@ -57,7 +55,7 @@
         - [`diag.net([callback])`](#diagnetcallback)
         - [`diag.sys([callback])`](#diagsyscallback)
         - [`diag.cmds([callback])`](#diagcmdscallback)
-    - [Network](#network)
+  - [Network](#network)
       - [`ping(id, [callback])`](#pingid-callback)
       - [`dht`](#dht)
         - [`dht.findprovs([callback])`](#dhtfindprovscallback)
@@ -69,30 +67,13 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-# API
+# API Reference
 
 We classify the API calls by 'core', 'extensions', 'tooling', and 'network', following the same API spec organization available at [ipfs/specs](https://github.com/ipfs/specs/tree/master/api).
 
 The tests folder also contains great examples that can be used to understand how this client library interacts with the HTTP-API. You can find the [tests here](test/api).
 
-
-## Callbacks and promises
-
-If you do not pass in a callback all api functions will return a `Promise`, for example
-
-```js
-ipfs.id()
-  .then(function (id) {
-    console.log('my id is: ', id)
-  })
-```
-
-This relies on a global `Promise` object. If you are in an environemnt where that is not
-yet available you need to bring your own polyfill.
-
-## Reference
-
-### Core
+## Core
 
 #### `version([callback])`
 
@@ -149,7 +130,7 @@ yet available you need to bring your own polyfill.
 
 ##### `log.tail([callback])`
 
-### Extensions
+## Extensions
 
 #### `add(arrayOrBufferOrStream, [callback])`
 
@@ -179,7 +160,7 @@ yet available you need to bring your own polyfill.
 
 - [tests](test/api/mount.spec.js)
 
-### Tooling
+## Tooling
 
 #### `commands([callback])`
 
@@ -201,7 +182,7 @@ yet available you need to bring your own polyfill.
 ##### `diag.sys([callback])`
 ##### `diag.cmds([callback])`
 
-### Network
+## Network
 
 #### `ping(id, [callback])`
 

CONTRIBUTING.md

@@ -6,7 +6,7 @@ You should have [node.js], [npm] and [gulp] installed.
 
 ## Linting
 
-Linting is done using [eslint] and the rules are based on [standard]
+Linting is done using [eslint] and the rules are based on [standard].
 
 ```bash
 $ gulp lint

README.md

@@ -18,6 +18,24 @@ IPFS API wrapper library in JavaScript
 $ npm install --save ipfs-api
 ```
 
+#### Running the daemon with the right port
+
+To interact with the API, you need to have a local daemon running. It needs to be open on the right port. `5001` is the default, and is used in the examples below, but it can be set to whatever you need.
+
+```sh
+# Show the ipfs config API port to check it is correct
+$ ipfs config Addresses.API
+/ip4/127.0.0.1/tcp/5001
+# Set it if it does not match the above output
+$ ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
+# Restart the daemon after changing the config
+
+# Run the daemon
+$ ipfs daemon
+```
+
+#### Importing the module and usage
+
 ```javascript
 var ipfsAPI = require('ipfs-api')
 
@@ -66,3 +84,37 @@ $ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://exam
 ## Usage
 
 See [API.md](API.md) and [`tests/api`](test/api) for details on available methods.
+
+### Callbacks and promises
+
+If you do not pass in a callback all API functions will return a `Promise`. For example:
+
+```js
+ipfs.id()
+  .then(function (id) {
+    console.log('my id is: ', id)
+  })
+  .catch(function(err) {
+  	console.log('Fail: ', err)
+  })
+```
+
+This relies on a global `Promise` object. If you are in an environment where that is not
+yet available you need to bring your own polyfill.
+
+## Contribute
+
+The js-ipfs API is a work in progress. As such, there's a few things you can do right now to help out:
+
+* **[Check out the existing issues](https://github.com/ipfs/js-ipfs-api/issues)**!
+* **Perform code reviews**. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
+* **Add tests**. There can never be enough tests.
+* **Contribute to the [FAQ repository](https://github.com/ipfs/faq/issues)** with any questions you have about IPFS or any of the relevant technology. A good example would be asking, 'What is a merkledag tree?'. If you don't know a term, odds are, someone else doesn't either. Eventually, we should have a good understanding of where we need to improve communications and teaching together to make IPFS and IPN better.
+
+## License
+
+MIT.
+
+# Want to hack on IPFS?
+
+[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)