docs: consolidate API docs and update readme files

.gitignore

@@ -18,9 +18,6 @@ node_modules
 # Build artefacts
 dist
 
-# Doc generation
-docs
-
 # Deployment files
 .npmrc
 

packages/ipfs/ISSUE_TEMPLATE.md → ISSUE_TEMPLATE.md

@@ -1,13 +1,16 @@
 <!--
 Thank you for reporting an issue.
 
-This issue tracker is for bugs and issues found within the JavaScript implementation of IPFS.
-If you require more general support please file an issue on our discuss forum. https://discuss.ipfs.io/
+This issue tracker is for bugs found within the JavaScript implementation of IPFS.
 
-Please fill in as much of the template below as you're able.
+If you are asking a question about how to use IPFS, please ask on https://discuss.ipfs.io
+
+Otherwise please fill in as much of the template below as possible.
 
 Version: output of `jsipfs version --all` if using the CLI or `ipfs.version((err, version) => {})` if using the instance.
+
 Platform: output of `uname -a` (UNIX), or version and 32 or 64-bit (Windows). If using in a Browser, please share the browser version as well.
+
 Subsystem: if known, please specify affected core module name (e.g Bitswap, libp2p, etc).
 
 If possible, please provide code that demonstrates the problem, keeping it as
@@ -21,7 +24,7 @@ simple and free of external dependencies as you are able.
 <!-- Bug, Feature, Question, Enhancement, Etc -->
 #### Type:
 
-<!-- 
+<!--
 One of following:
   Critical - System crash, application panic.
   High - The main functionality of the application does not work, API breakage, repo format breakage, etc.

README.md

@@ -4,12 +4,7 @@
   </a>
 </p>
 
-<h3 align="center">The JavaScript implementation of the IPFS protocol.</h3>
-
-<p align="center">
-  <a href="http://protocol.ai"><img src="https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat" /></a>
-  <a href="http://ipfs.io/"><img src="https://img.shields.io/badge/project-IPFS-blue.svg?style=flat" /></a>
-</p>
+<h3 align="center">The JavaScript implementation of the IPFS protocol</h3>
 
 <p align="center">
   <a href="https://riot.im/app/#/room/#ipfs-dev:matrix.org"><img src="https://img.shields.io/badge/matrix-%23ipfs%3Amatrix.org-blue.svg?style=flat" /> </a>
@@ -27,122 +22,64 @@
 
 > **Upgrading from <=0.40 to 0.41?** See the [release notes](https://github.com/ipfs/js-ipfs/issues/2656) for the list of API changes and the [migration guide](https://gist.github.com/alanshaw/04b2ddc35a6fff25c040c011ac6acf26).
 
-### Project status - `Alpha` <!-- omit in toc -->
-
-We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons 🐉.
+We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉..
 
-**Want to get started?** Check our [examples folder](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser.
+## Getting started
 
-🚨 **Please read this** 🚨 The [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table), a fundamental piece for automatic content and peer discovery is not yet complete. There are multiple applications that can be built without this service but nevertheless it is fundamental to getting that magic IPFS experience. The current status is that implementation is done and merged and we're working on performance issues. Expect the DHT to be available in a release very soon.
-
-[**`Weekly Core Implementations Call`**](https://github.com/ipfs/team-mgmt/issues/992)
+* Look into the [examples folder](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-beta.ipfs.io for tips, how-tos and more
 
 ## Tech Lead <!-- omit in toc -->
 
 [David Dias](https://github.com/daviddias)
 
 ## Lead Maintainer <!-- omit in toc -->
 
-[Alan Shaw](https://github.com/alanshaw)
+[Alex Potsides](http://github.com/achingbrain)
 
 ## Table of Contents <!-- omit in toc -->
 
+- [Getting started](#getting-started)
+- [Documentation](#documentation)
 - [Structure](#structure)
-- [Development](#development)
-  - [Clone and install dependencies](#clone-and-install-dependencies)
-  - [Run tests](#run-tests)
-  - [Lint](#lint)
-  - [Build a dist version](#build-a-dist-version)
-  - [Publishing new versions](#publishing-new-versions)
-  - [Using prerelease versions](#using-prerelease-versions)
-- [Contribute](#contribute)
-  - [Want to hack on IPFS?](#want-to-hack-on-ipfs)
+- [Want to hack on IPFS?](#want-to-hack-on-ipfs)
 - [License](#license)
 
+## Documentation
+
+* [Core API](./docs/core-api)
+* [Examples](./examples)
+* [Development]('./docs/DEVELOPMENT.md)
+
 ## Structure
 
 This project is broken into several modules, their purposes are:
 
 * [`/packages/ipfs`](./packages/ipfs) The core implementation
 * [`/packages/ipfs-http-client`](./packages/ipfs-http-client) A client for the RPC-over-HTTP API presented by both js-ipfs and go-ipfs
 * [`/packages/interface-ipfs-core`](./packages/interface-ipfs-core) Tests to ensure adherance of an implementation to the spec
-* [`/packages/ipfs-utils`](./packages/ipfs-utils) Helpers and utilities common to core and the HTTP RPC API client
-* [`/packages/ipfs-mfs`](./packages/ipfs-mfs) The mfs implementation
-* [`/packages/ipfs-multipart`](./packages/ipfs-multipart) A module that handles adding files via multipart HTTP requests for core and the mfs
-
-## Development
-
-### Clone and install dependencies
-
-```sh
-> git clone https://github.com/ipfs/js-ipfs.git
-> cd js-ipfs
-> npm install
-```
-
-This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, deduping and hoisting dependencies into the root folder.
-
-If later you add new dependencies to submodules or just wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root.
-
-See the scripts section of the root [`package.json`](./package.json) for more commands.
-
-### Run tests
-
-```sh
-# run all the unit tests
-> npm test
-
-# run just IPFS tests in Node.js
-> npm run test:node
+* [`/packages/ipfs-core-utils`](./packages/ipfs-core-utils) Helpers and utilities common to core and the HTTP RPC API client
 
-# run just IPFS tests in a browser
-> npm run test:browser
+## Want to hack on IPFS?
 
-# run just IPFS tests in a webworker
-> npm run test:webworker
-```
-
-More granular test suites can be run from each submodule.
-
-Please see the `package.json` in each submodule for available commands.
-
-### Lint
-
-Please run the linter before submitting a PR, the build will not pass if it fails:
-
-```sh
-> npm run lint
-```
-
-### Build a dist version
-
-```sh
-> npm run build
-```
-
-### Publishing new versions
-
-1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions
-2. From the root of this repo run `npm run release` and follow the on screen prompts.  It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version
-
-### Using prerelease versions
-
-Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`.
+[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
 
-## Contribute
+The IPFS implementation in JavaScript needs your help!  There are a few things you can do right now to help out:
 
-IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out:
+Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md).
 
-- Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically.
-- **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs.
-- Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better.
+- **Check out existing issues** The [issue list](https://github.com/ipfs/js-ipfs/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
+- **Look at the [IPFS Roadmap](https://github.com/ipfs/roadmap)** This are the high priority items being worked on right now
+- **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.
+- **Join the [Weekly Core Implementations Call](https://github.com/ipfs/team-mgmt/issues/992)** it's where everyone discusses what's going on with IPFS and what's next
 
-### 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)
-
-Check out [ipfs/community/CONTRIBUTING_JS.md](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for details on coding standards, commit messages and other project conventions
 
 ## License
 

packages/ipfs/docs/config.md → docs/CONFIG.md

@@ -1,8 +1,32 @@
-# The js-ipfs config file
+# The js-ipfs config file <!-- omit in toc -->
 
 The js-ipfs config file is a JSON document located in the root directory of the js-ipfs repository.
 
-#### Profiles
+## Table of Contents <!-- omit in toc -->
+
+- [Profiles](#profiles)
+- [`Addresses`](#addresses)
+  - [`API`](#api)
+  - [`Delegates`](#delegates)
+  - [`Gateway`](#gateway)
+  - [`Swarm`](#swarm)
+- [`Bootstrap`](#bootstrap)
+- [`Datastore`](#datastore)
+  - [`Spec`](#spec)
+- [`Discovery`](#discovery)
+  - [`MDNS`](#mdns)
+  - [`webRTCStar`](#webrtcstar)
+- [`Identity`](#identity)
+  - [`PeerID`](#peerid)
+  - [`PrivKey`](#privkey)
+- [`Keychain`](#keychain)
+- [`Pubsub`](#pubsub)
+  - [`Router`](#router)
+  - [`Enabled`](#enabled)
+- [`Swarm`](#swarm-1)
+  - [`ConnMgr`](#connmgr)
+
+## Profiles
 
 Configuration profiles allow to tweak configuration quickly. Profiles can be
 applied with `--profile` flag to `ipfs init` or with the `ipfs config profile
@@ -40,29 +64,8 @@ Available profiles:
 
   Inverse of "lowpower" profile.
 
-## Table of Contents
-
-- [`Addresses`](#addresses)
-  - [`API`](#api)
-  - [`Delegates`](#delegates)
-  - [`Gateway`](#gateway)
-  - [`Swarm`](#swarm)
-- [`Bootstrap`](#bootstrap)
-- [`Datastore`](#datastore)
-  - [`Spec`](#spec)
-- [`Discovery`](#discovery)
-  - [`MDNS`](#mdns)
-  - [`webRTCStar`](#webrtcstar)
-- [`Identity`](#identity)
-  - [`PeerID`](#peerid)
-  - [`PrivKey`](#privkey)
-- [`Keychain`](#keychain)
-- [`Pubsub`](#pubsub)
-  - [`Router`](#router)
-- [`Swarm`](#swarm)
-  - [`ConnMgr`](#connmgr)
-
 ## `Addresses`
+
 Contains information about various listener addresses to be used by this node.
 
 ### `API`

docs/DEVELOPMENT.md

@@ -0,0 +1,65 @@
+# Development <!-- omit in toc -->
+
+- [Clone and install dependencies](#clone-and-install-dependencies)
+- [Run tests](#run-tests)
+- [Lint](#lint)
+- [Build a dist version](#build-a-dist-version)
+- [Publishing new versions](#publishing-new-versions)
+- [Using prerelease versions](#using-prerelease-versions)
+
+## Clone and install dependencies
+
+```sh
+> git clone https://github.com/ipfs/js-ipfs.git
+> cd js-ipfs
+> npm install
+```
+
+This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, deduping and hoisting dependencies into the root folder.
+
+If later you add new dependencies to submodules or just wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root.
+
+See the scripts section of the root [`package.json`](./package.json) for more commands.
+
+## Run tests
+
+```sh
+# run all the unit tests
+> npm test
+
+# run just IPFS tests in Node.js
+> npm run test:node
+
+# run just IPFS tests in a browser
+> npm run test:browser
+
+# run just IPFS tests in a webworker
+> npm run test:webworker
+```
+
+More granular test suites can be run from each submodule.
+
+Please see the `package.json` in each submodule for available commands.
+
+## Lint
+
+Please run the linter before submitting a PR, the build will not pass if it fails:
+
+```sh
+> npm run lint
+```
+
+## Build a dist version
+
+```sh
+> npm run build
+```
+
+## Publishing new versions
+
+1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions
+2. From the root of this repo run `npm run release` and follow the on screen prompts.  It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version
+
+## Using prerelease versions
+
+Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`.

docs/IPFS.md

@@ -0,0 +1,25 @@
+# IPFS module <!-- omit in toc -->
+
+These are functions not in the [Core API](#core-api) but that are specific to [`ipfs`](../packages/ipfs).
+
+## Table of contents <!-- omit in toc -->
+
+- [Constructor](#constructor)
+  - [`options.repo`](#optionsrepo)
+  - [`options.repoAutoMigrate`](#optionsrepoautomigrate)
+  - [`options.init`](#optionsinit)
+  - [`options.start`](#optionsstart)
+  - [`options.pass`](#optionspass)
+  - [`options.silent`](#optionssilent)
+  - [`options.relay`](#optionsrelay)
+  - [`options.offline`](#optionsoffline)
+  - [`options.preload`](#optionspreload)
+  - [`options.EXPERIMENTAL`](#optionsexperimental)
+  - [`options.config`](#optionsconfig)
+  - [`options.ipld`](#optionsipld)
+  - [`options.libp2p`](#optionslibp2p)
+  - [`options.connectionManager`](#optionsconnectionmanager)
+- [Instance methods](#instance-methods)
+  - [`node.start()`](#nodestart)
+  - [`node.stop()`](#nodestop)
+

docs/README.md

@@ -0,0 +1,26 @@
+# IPFS Docs <!-- omit in toc -->
+
+- [API Docs](#api-docs)
+- [How tos and other documentation](#how-tos-and-other-documentation)
+- [Development documentation](#development-documentation)
+
+## API Docs
+
+`ipfs` can run as part of your program (an in-process node) or as a standalone daemon process that can be communicated with via an HTTP RPC API using the [`ipfs-http-client`](../packages/ipfs-http-api) module.
+
+Whether accessed directly or over HTTP, both methods support the full [Core API](#core-api).  In addition other methods are available to construct instances of each module, etc.
+
+* [Core API docs](./core-api/README.md)
+* [IPFS API]('../packages/ipfs/README.md)
+* [IPFS-HTTP-CLIENT API]('../packages/ipfs-http-client/README.md)
+
+## How tos and other documentation
+
+* [How to run js-IPFS in the browser](./BROWSERS.md)
+* [js-IPFS configuration options](./CONFIG.md)
+
+## Development documentation
+
+* [Release issue template](./RELEASE_ISSUE_TEMPLATE.md)
+* [Early testers](./EARLY_TESTERS.md)
+* [Releases](./RELEASES.md)