docs: Add a README home page to API.

docs/api/README.md

@@ -1,4 +1,58 @@
-# OrbitDB
+OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS
+as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges making OrbitDB an excellent choice for p2p and decentralized apps, blockchain applications and local first web applications.
 
-## Getting Started
+To install OrbitDB:
 
+```bash
+npm install orbit-db
+```
+
+IPFS is also required:
+
+```bash
+npm install ipfs-core
+```
+
+Instantiate OrbitDB and open a new database:
+
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB } from 'orbit-db'
+
+const ipfs = await create() // IPFS is required for storage and syncing
+const orbitdb = await OrbitDB({ ipfs })
+const mydb = await orbitdb.open('mydb')
+const dbAddress = mydb.address // E.g. /orbitdb/zdpuAuK3BHpS7NvMBivynypqciYCuy2UW77XYBPUYRnLjnw13
+@example <caption>Open an existing database using its multiformat address:</caption>
+const mydb = await orbitdb.open(dbAddress)
+```
+
+Use with pre-configured identities:
+
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, Identities } from 'orbit-db'
+import CustomStorage from './custom-storage.js'
+
+const storage = await CustomStorage()
+const identities = await Identities({ storage })
+const ipfs = await create() // IPFS is required for storage and syncing
+const orbitdb = await OrbitDB({ ipfs, identities })
+const mydb = await orbitdb.open('mydb')
+```
+
+Use with existing identities:
+
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, Identities } from 'orbit-db'
+
+const identities = await Identities()
+await identities.createIdentity('userA')
+
+const ipfs = await create() // IPFS is required for storage and syncing
+const orbitdb = await OrbitDB({ ipfs, identities, id: 'userA' })
+const mydb = await orbitdb.open('mydb')
+```
+
+See the [OrbitDB module](./module-OrbitDB.html) for more information about how to open databases.

package.json

@@ -62,7 +62,7 @@
     "build:examples": "webpack --config conf/webpack.example.config.js",
     "build:dist": "webpack --config conf/webpack.config.js",
     "build:debug": "webpack --config conf/webpack.debug.config.js",
-    "build:docs": "jsdoc -c ./conf/jsdoc/jsdoc.json -r src/** -d ./docs/api",
+    "build:docs": "jsdoc -c ./conf/jsdoc/jsdoc.json -r src/** -d ./docs/api -R ./docs/api/README.md",
     "build:tests": "rm -f test/browser/bundle.js* && webpack --config ./conf/webpack.tests.config.js",
     "prepublishOnly": "npm run build",
     "lint": "standard --env=mocha",

src/orbitdb.js

@@ -1,52 +1,6 @@
 /**
 * @module OrbitDB
-* @description
+* @description Provides an interface for users to interact with OrbitDB.
-* OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses
-* IPFS as its data storage and Libp2p Pubsub to automatically sync databases
-* with peers. It's an eventually consistent database that uses Merkle-CRDTs
-* for conflict-free database writes and merges making OrbitDB an excellent
-* choice for p2p and decentralized apps, blockchain applications and local
-* first web applications.
-*
-* To install OrbitDB:
-* ```bash
-* npm install orbit-db
-* ```
-*
-* IPFS is also required:
-* ```bash
-* npm install ipfs-core
-* ```
-* @example <caption>Instantiate OrbitDB and open a new database:</caption>
-* import { create } from 'ipfs-core'
-* import { OrbitDB } from 'orbit-db'
-*
-* const ipfs = await create() // IPFS is required for storage and syncing
-* const orbitdb = await OrbitDB({ ipfs })
-* const mydb = await orbitdb.open('mydb')
-* const dbAddress = mydb.address // E.g. /orbitdb/zdpuAuK3BHpS7NvMBivynypqciYCuy2UW77XYBPUYRnLjnw13
-* @example <caption>Open an existing database using its multiformat address:</caption>
-* const mydb = await orbitdb.open(dbAddress)
-* @example <caption>Use with pre-configured identities:</caption>
-* import { create } from 'ipfs-core'
-* import { OrbitDB, Identities } from 'orbit-db'
-* import CustomStorage from './custom-storage.js'
-*
-* const storage = await CustomStorage()
-* const identities = await Identities({ storage })
-* const ipfs = await create() // IPFS is required for storage and syncing
-* const orbitdb = await OrbitDB({ ipfs, identities })
-* const mydb = await orbitdb.open('mydb')
-* @example <caption>Use with existing identities:</caption>
-* import { create } from 'ipfs-core'
-* import { OrbitDB, Identities } from 'orbit-db'
-*
-* const identities = await Identities()
-* await identities.createIdentity('userA')
-*
-* const ipfs = await create() // IPFS is required for storage and syncing
-* const orbitdb = await OrbitDB({ ipfs, identities, id: 'userA' })
-* const mydb = await orbitdb.open('mydb')
 */
 import { getDatabaseType } from './db/index.js'
 import KeyStore from './key-store.js'