docs: consolidate and update docs (#3364)

achingbrain · web-flow · commit 933ea01d736c · 2020-11-02T12:33:51.000Z
* Consolidates docs under `/docs`
* Adds missing licenses, CoC, READMEs, etc
* Updates docs where information was incorrect
diff --git a/README.md b/README.md
@@ -29,24 +29,15 @@
 
 > A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the IPFS [Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/api) enabling applications to change between an embedded js-ipfs node and any remote IPFS node without having to change the code. In addition, this client library implements a set of utility functions.
 
-## Getting started
-
-* Look into the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser
-* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node
-* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
-* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
-* Check out https://docs.ipfs.io for tips, how-tos and more
-
-## Lead Maintainer
+## Lead Maintainer <!-- omit in toc -->
 
 [Alex Potsides](http://github.com/achingbrain)
 
-## Table of Contents
+## Table of Contents <!-- omit in toc -->
 
-- [Getting started](#getting-started)
-- [Lead Maintainer](#lead-maintainer)
-- [Table of Contents](#table-of-contents)
-- [Install](#install)
+- [Getting Started](#getting-started)
+  - [Install](#install)
+  - [Next Steps](#next-steps)
 - [Usage](#usage)
   - [API](#api)
   - [Additional Options](#additional-options)
@@ -58,12 +49,9 @@
     - [URL source](#url-source)
       - [`urlSource(url)`](#urlsourceurl)
       - [Example](#example-1)
-  - [IPLD Formats](#ipld-formats)
   - [Running the daemon with the right port](#running-the-daemon-with-the-right-port)
   - [Importing the module and usage](#importing-the-module-and-usage)
-  - [Importing a sub-module and usage](#importing-a-sub-module-and-usage)
   - [In a web browser](#in-a-web-browser)
-  - [CORS](#cors)
   - [Custom Headers](#custom-headers)
   - [Global Timeouts](#global-timeouts)
 - [Development](#development)
@@ -72,7 +60,11 @@
 - [Historical context](#historical-context)
 - [License](#license)
 
-## Install
+## Getting Started
+
+We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉..
+
+### Install
 
 This module uses node.js, and can be installed through npm:
 
@@ -82,13 +74,24 @@ npm install --save ipfs-http-client
 
 Both the Current and Active LTS versions of Node.js are supported. Please see [nodejs.org](https://nodejs.org/) for what these currently are.
 
+### Next Steps
+
+* Read the [docs](https://github.com/ipfs/js-ipfs/tree/master/docs)
+* Look into the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser
+* Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node
+* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
+* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
+* Check out https://docs.ipfs.io for tips, how-tos and more
+* See https://blog.ipfs.io for news and more
+* Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io
+
 ## Usage
 
 ### API
 
 [![IPFS Core API Compatible](https://cdn.rawgit.com/ipfs/interface-ipfs-core/master/img/badge.svg)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core)
 
-> `js-ipfs-http-client` implements the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) - please follow the previous link to see the the methods available.
+> `js-ipfs-http-client` implements the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) - please follow the previous link to see the methods available.
 
 ### Additional Options
 
@@ -107,7 +110,6 @@ Call this on your client instance to return an object containing the `host`, `po
 
 Aside from the default export, `ipfs-http-client` exports various types and utilities that are included in the bundle:
 
-- [`Buffer`](https://www.npmjs.com/package/buffer)
 - [`multiaddr`](https://www.npmjs.com/package/multiaddr)
 - [`multibase`](https://www.npmjs.com/package/multibase)
 - [`multicodec`](https://www.npmjs.com/package/multicodec)
@@ -192,53 +194,6 @@ console.log(file)
 */
 ```
 
-### IPLD Formats
-
-By default an instance of the client supports the following [IPLD formats](https://github.com/ipld/interface-ipld-format), which are enough to do all core IPFS operations:
-
-  * [dag-pb](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-pb.md)
-  * [dag-cbor](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md)
-  * [raw](https://github.com/ipld/specs/issues/223)
-
-If your application requires support for extra codecs, you can configure them as follows:
-
-1. Configure the [IPLD layer](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md#optionsipld) of your IPFS daemon to support the codec. This step is necessary so the node knows how to prepare data received over HTTP to be passed to IPLD for serialization:
-    ```javascript
-    const ipfs = require('ipfs')
-
-    const node = await ipfs({
-      ipld: {
-        // either specify them as part of the `formats` list
-        formats: [
-          require('my-format')
-        ],
-
-        // or supply a function to load them dynamically
-        loadFormat: async (format) => {
-          return require(format)
-        }
-      }
-    })
-2. Configure your IPFS HTTP API Client to support the codec. This is necessary so that the client can send the data to the IPFS node over HTTP:
-    ```javascript
-    const ipfsHttpClient = require('ipfs-http-client')
-
-    const client = ipfsHttpClient({
-      url: 'http://127.0.0.1:5002',
-      ipld: {
-        // either specify them as part of the `formats` list
-        formats: [
-          require('my-format')
-        ],
-
-        // or supply a function to load them dynamically
-        loadFormat: async (format) => {
-          return require(format)
-        }
-      }
-    })
-    ```
-
 ### 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.
@@ -273,15 +228,6 @@ const ipfs = ipfsClient({ host: 'localhost', port: '5001', protocol: 'http' })
 const ipfs = ipfsClient({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })
 ```
 
-### Importing a sub-module and usage
-
-```javascript
-const bitswap = require('ipfs-http-client/src/bitswap')('/ip4/127.0.0.1/tcp/5001')
-
-const list = await bitswap.wantlist()
-// ...
-```
-
 ### In a web browser
 
 **through Browserify**
@@ -331,17 +277,6 @@ If you omit the host and port, the client will parse `window.host`, and use this
 const ipfs = window.IpfsHttpClient()
 ```
 
-### CORS
-
-In a web browser IPFS HTTP client (either browserified or CDN-based) might encounter an error saying that the origin is not allowed. This would be a CORS ("Cross Origin Resource Sharing") failure: IPFS servers are designed to reject requests from unknown domains by default. You can whitelist the domain that you are calling from by changing your ipfs config like this:
-
-```console
-$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin  '["http://example.com"]'
-$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'
-```
-
-If you are using `js-ipfs`, substitute `ipfs` for `jsipfs` in the commands above.
-
 ### Custom Headers
 
 If you wish to send custom headers with each request made by this library, for example, the Authorization header. You can use the config to do so:
