docs: consolidate API docs and update readme files (ipfs#2944)

* docs: consolidate API docs and update readme files

Moves api docs into `/docs` folder similarly to how js-libp2p has organised
their docs.

Tries to trim readmes down a bit to make them more digestible and
adds links to futher information on different topics.

Also reinstates dependency statuses.

Co-authored-by: Hugo Dias <[email protected]>

Author: achingbrain

ISSUE_TEMPLATE.md

@@ -0,0 +1,31 @@
+# IPFS Architecture
+
+![](../img/architecture.png)
+
+[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png)
+
+What does this image explain?
+
+- IPFS uses `ipfs-repo` which picks `fs` or `indexeddb` as its storage drivers, depending if it is running in Node.js or in the Browser.
+- The exchange protocol, `bitswap`, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation.
+- The DAG API (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc).
+- The Files API uses `ipfs-unixfs-engine` to import and export files to and from IPFS.
+- libp2p, the network stack of IPFS, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more.
+
+## Code Architecture and folder Structure
+
+![](img/overview.png)
+
+### Source code
+
+```Bash
+> tree src -L 2
+src                 # Main source code folder
+├── cli             # Implementation of the IPFS CLI
+│   └── ...
+├── http            # The HTTP-API implementation of IPFS as defined by HTTP API spec
+├── core            # IPFS implementation, the core (what gets loaded in browser)
+│   ├── components  # Each of IPFS subcomponent
+│   └── ...
+└── ...
+```

README.md

@@ -0,0 +1,39 @@
+# IPFS CLI <!-- omit in toc -->
+
+## Table of contents <!-- omit in toc -->
+
+- [Overview](#overview)
+- [Configuration](#configuration)
+
+## Overview
+
+In order to use js-ipfs as a CLI, you must install it with the `global` flag. Run the following (even if you have ipfs installed locally):
+
+```bash
+npm install ipfs --global
+```
+
+The CLI is available by using the command `jsipfs` in your terminal. This is aliased, instead of using `ipfs`, to make sure it does not conflict with the [Go implementation](https://github.com/ipfs/go-ipfs).
+
+Once installed, please follow the [Getting Started Guide](https://docs.ipfs.io/introduction/usage/) to learn how to initialize your node and run the daemon.
+
+```sh
+# Install js-ipfs globally
+> jsipfs --help
+Commands:
+  bitswap               A set of commands to manipulate the bitswap agent.
+  block                 Manipulate raw IPFS blocks.
+  bootstrap             Show or edit the list of bootstrap peers.
+  commands              List all available commands
+  config <key> [value]  Get and set IPFS config values
+  daemon                Start a long-running daemon process
+# ...
+```
+
+## Configuration
+
+`js-ipfs` uses some different default config values, so that they don't clash directly with a go-ipfs node running in the same machine. These are:
+
+- default repo location: `~/.jsipfs` (can be changed with env variable `IPFS_PATH`)
+- default swarm port: `4002`
+- default API port: `5002`

docs/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+
+# Running IPFS as a daemon <!-- omit in toc -->
+
+> How to run a long-lived IPFS process
+
+## Table of contents <!-- omit in toc -->
+
+- [CLI](#cli)
+- [Programmatic](#programmatic)
+
+## CLI
+
+To start a daemon on the CLI, use the `daemon` command:
+
+```console
+jsipfs daemon
+```
+
+The IPFS Daemon exposes the API defined in the [HTTP API spec](https://docs.ipfs.io/reference/api/http/). You can use any of the IPFS HTTP-API client libraries with it, such as: [ipfs-http-client](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client).
+
+## Programmatic
+
+If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out the [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl) module.
+
+```javascript
+const { createFactory } = require('ipfsd-ctl')
+const factory = createFactory({
+  type: 'proc' // or 'js' to run in a separate process
+})
+
+const node = await factory.create()
+
+// print the node ide
+console.info(await node.id())
+```

docs/CLI.md

@@ -0,0 +1,16 @@
+# Configuring Delegate Routers
+
+If you need to support Delegated Content and/or Peer Routing, you can enable it by specifying the multiaddrs of your delegate nodes in the config via `options.config.Addresses.Delegates`. If you need to run a delegate router we encourage you to run your own, with go-ipfs. You can see instructions for doing so in the [delegated routing example](https://github.com/libp2p/js-libp2p/tree/master/examples/delegated-routing).
+
+If you are not able to run your own delegate router nodes, we currently have two nodes that support delegated routing. **Important**: As many people may be leveraging these nodes, performance may be affected, which is why we recommend running your own nodes in production.
+
+Available delegate multiaddrs are:
+- `/dns4/node0.delegate.ipfs.io/tcp/443/https`
+- `/dns4/node1.delegate.ipfs.io/tcp/443/https`
+
+**Note**: If more than 1 delegate multiaddr is specified, the actual delegate will be randomly selected on startup.
+
+**Note**: If you wish to use delegated routing and are creating your node _programmatically_ in Node.js or the browser you must `npm install libp2p-delegated-content-routing` and/or `npm install libp2p-delegated-peer-routing` and provide configured instances of them in [`options.libp2p`](#optionslibp2p). See the module repos for further instructions:
+
+- https://github.com/libp2p/js-libp2p-delegated-content-routing
+- https://github.com/libp2p/js-libp2p-delegated-peer-routing

docs/DAEMON.md

@@ -0,0 +1,92 @@
+# Development <!-- omit in toc -->
+
+> Getting started with development on IPFS
+
+## Table of contents <!-- omit in toc -->
+
+- [Clone and install dependencies](#clone-and-install-dependencies)
+- [Run tests](#run-tests)
+  - [Run interop tests](#run-interop-tests)
+  - [Run benchmark tests](#run-benchmark-tests)
+- [Lint](#lint)
+- [Build a dist version](#build-a-dist-version)
+
+## Clone and install dependencies
+
+```sh
+> git clone https://github.com/ipfs/js-ipfs.git
+> cd js-ipfs
+> npm install
+```
+
+## Run tests
+
+```sh
+# run all the unit tests
+> npm test
+
+# run individual tests (findprovs)
+> npm run test -- --grep findprovs
+
+# run just IPFS tests in Node.js
+> npm run test:node
+
+# run just IPFS core tests
+> npm run test:node:core
+
+# run just IPFS HTTP-API tests
+> npm run test:node:http
+
+# run just IPFS CLI tests
+> npm run test:cli
+
+# run just IPFS core tests in the Browser (Chrome)
+> npm run test:browser
+
+# run some interface tests (block API) on Node.js
+> npm run test:node:interface -- --grep '.block'
+```
+
+### Run interop tests
+
+
+```sh
+# run the interop tests with the default go-IPFS
+> npm run test:interop
+
+# run the interop tests with a different go-IPFS
+> IPFS_EXEC_GO=/path/to/ipfs npm run test:interop
+```
+
+### Run benchmark tests
+
+```sh
+# run all the benchmark tests
+> npm run benchmark
+
+# run just IPFS benchmarks in Node.js
+> npm run benchmark:node
+
+# run just IPFS benchmarks in Node.js for an IPFS instance
+> npm run benchmark:node:core
+
+# run just IPFS benchmarks in Node.js for an IPFS daemon
+> npm run benchmark:node:http
+
+# run just IPFS benchmarks in the browser (Chrome)
+> npm run benchmark:browser
+```
+
+## Lint
+
+**Conforming to linting rules is a prerequisite to commit to js-ipfs.**
+
+```sh
+> npm run lint
+```
+
+## Build a dist version
+
+```sh
+> npm run build
+```

docs/DELEGATE_ROUTERS.md

@@ -0,0 +1,32 @@
+
+# Running js-ipfs with Docker
+
+We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/
+
+All branches in the Github repository maps to a tag in Docker Hub, except `master` Git branch which is mapped to `latest` Docker tag.
+
+You can run js-ipfs like this:
+
+```
+$ docker run -it -p 4002:4002 -p 4003:4003 -p 5002:5002 -p 9090:9090 ipfs/js-ipfs:latest
+
+initializing ipfs node at /root/.jsipfs
+generating 2048-bit RSA keypair...done
+peer identity: Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
+to get started, enter:
+
+         jsipfs files cat /ipfs/QmfGBRT6BbWJd7yUc2uYdaUZJBbnEFvTqehPFoSMQ6wgdr/readme
+
+Initializing daemon...
+Using wrtc for webrtc support
+Swarm listening on /ip4/127.0.0.1/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
+Swarm listening on /ip4/172.17.0.2/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
+Swarm listening on /ip4/127.0.0.1/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
+Swarm listening on /ip4/172.17.0.2/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
+API is listening on: /ip4/0.0.0.0/tcp/5002
+Gateway (readonly) is listening on: /ip4/0.0.0.0/tcp/9090
+Daemon is ready
+
+$ curl --silent localhost:5002/api/v0/id | jq .ID
+"Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS"
+```