cleanup documentations (#86)

* updated README.md for contributing guide * updated website/packages front matters * separated testcontainers into another category * updated testcontainers with more information * cleanup jellyfish docs structure * fixed top nav link * increased code font size
DeFiCh · Mar 29, 2021 · 3e7b15e · 3e7b15e
1 parent 1e1a09e
commit 3e7b15e
Show file tree

Hide file tree

Showing 23 changed files with 208 additions and 156 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,7 +18,7 @@ Please follow the guidelines outlined at https://github.com/DeFiCh/.github/blob/
 
 ## Documentation
 
-Each pull request with feature change should have accompanying documentations under the `docs/` folder.
+Each pull request with feature change should have accompanying documentations under the `website/` folder.
 
 ## Explicit over implicit
 

diff --git a/README.md b/README.md
@@ -6,7 +6,8 @@
 
 # @defichain/jellyfish
 
-A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin.
+A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized
+finance on Bitcoin.
 
 > 🚧 Work in progress, `3/193` rpc completed.
 
@@ -65,38 +66,35 @@ const oceanClient = new Client(new OceanProvider(), options)
 
 [![Netlify Status](https://api.netlify.com/api/v1/badges/c5b7a65e-aeec-4e12-a7b7-300cbc1a8069/deploy-status)](https://app.netlify.com/sites/cranky-franklin-5e59ef/deploys)
 
+Following the idea of everything in main is production ready; all pull request must be accompanied by a documentation
+change under the `website/` folder. Hence, the main branch should be treated as a release with documentations.
+
 ```
 // TODO(fuxingloh): 
 Documentation can be found at `https://jellyfish.defichain.com`?
 + Community Links
 ```
 
-## Packages
-
-* `@defichain/jellyfish` bundled usage entrypoint with conventional defaults for 4 bundles: `umd`, `esm`, `cjs`
-  and `d.ts`
-* `@defichain/jellyfish-api-core` is a protocol agnostic DeFiChain client interfaces, with a "foreign function interface"
-  design.
-* `@defichain/jellyfish-api-jsonrpc` implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification.
-* `@defichain/jellyfish-json` allows parsing of JSON with `'lossless'`, `'bignumber'` and `'number'` numeric precision.
-* `@defichain/jellyfish-network` contains DeFi blockchain various network configuration for main, net and regtest.
-* `@defichain/testcontainers` provides a lightweight, throw away instances for DeFiD node provisioned automatically in
-  Docker container.
-
-### Latest Releases
-
-|package|@latest|@next|
-|---|---|---|
-|`@defichain/jellyfish`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)|
-|`@defichain/jellyfish-api-core`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-api-core)](https://www.npmjs.com/package/@defichain/jellyfish-api-core/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-api-core/next)](https://www.npmjs.com/package/@defichain/jellyfish-api-core/v/next)|
-|`@defichain/jellyfish-api-jsonrpc`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-api-jsonrpc)](https://www.npmjs.com/package/@defichain/jellyfish-api-jsonrpc/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-api-jsonrpc/next)](https://www.npmjs.com/package/@defichain/jellyfish-api-jsonrpc/v/next)|
-|`@defichain/jellyfish-json`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-json)](https://www.npmjs.com/package/@defichain/jellyfish-json/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-json/next)](https://www.npmjs.com/package/@defichain/jellyfish-json/v/next)|
-|`@defichain/jellyfish-network`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-network)](https://www.npmjs.com/package/@defichain/jellyfish-network/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-network/next)](https://www.npmjs.com/package/@defichain/jellyfish-network/v/next)|
-|`@defichain/testcontainers`|[![npm](https://img.shields.io/npm/v/@defichain/testcontainers)](https://www.npmjs.com/package/@defichain/testcontainers/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/testcontainers/next)](https://www.npmjs.com/package/@defichain/testcontainers/v/next)|
+### Packages
+
+Jellyfish follows a monorepo methodology, all maintained packages are in the same repo and published with the same version tag.
+
+[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)
+[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)
+
+Package                                            | Description
+---------------------------------------------------|-------------
+`@defichain/jellyfish`                             | Library bundled usage entrypoint with conventional defaults for 4 bundles: umd, esm, cjs and d.ts
+`@defichain/jellyfish-api-core`                    | A protocol agnostic DeFi Blockchain client interfaces, with a "foreign function interface" design.
+`@defichain/jellyfish-api-jsonrpc`                 | Implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification.
+`@defichain/jellyfish-json`                        | Allows parsing of JSON with 'lossless', 'bignumber' and 'number' numeric precision.
+`@defichain/jellyfish-network`                     | Contains DeFi blockchain various network configuration for main, net and regtest.
+`@defichain/testcontainers`                        | Provides a lightweight, throw away instances for DeFiD node provisioned automatically in a Docker container.
 
 ## Developing & Contributing
 
-Thanks for contributing, here is our [contributing guidelines](CONTRIBUTING.md).
+Thanks for contributing, appreciate all the help we can get. Feel free to make a pull-request, we will guide you along
+the way to make it mergeable. Here are some of our documented [contributing guidelines](CONTRIBUTING.md).
 
 We use `npm 7` for this project, it's required to set
 up [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).

diff --git a/packages/jellyfish-api-core/package.json b/packages/jellyfish-api-core/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/jellyfish-api-core",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/packages/jellyfish-api-jsonrpc/package.json b/packages/jellyfish-api-jsonrpc/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/jellyfish-api-jsonrpc",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/packages/jellyfish-json/package.json b/packages/jellyfish-json/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/jellyfish-json",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/packages/jellyfish-network/package.json b/packages/jellyfish-network/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/jellyfish-network",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/packages/jellyfish/package.json b/packages/jellyfish/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/jellyfish",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/packages/testcontainers/package.json b/packages/testcontainers/package.json
@@ -2,10 +2,11 @@
   "private": false,
   "name": "@defichain/testcontainers",
   "version": "0.0.0",
-  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin",
+  "description": "A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin",
   "keywords": [
     "DeFiChain",
-    "JavaScript",
+    "DeFi",
+    "Blockchain",
     "API",
     "Bitcoin"
   ],

diff --git a/website/README.md b/website/README.md
@@ -1,25 +1,19 @@
 # jellyfish/website
 
-> This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+`/website/*` contains the documentation for jellyfish; built using [Docusaurus 2](https://v2.docusaurus.io/), a modern
+static website generator.
 
-## Installation
+## Writing documentations
 
-```console
-npm i
-```
+Following the idea of everything in master is production ready; all pull request should be accompanied by a
+documentation change. Hence, the master/main branch should be treated as a release as so are the documentations.
 
-## Local Development
+## Local Setup
 
-```console
-npm run start
-```
-
-This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
-
-## Build
+This command starts a local development server and open up a browser window. Most changes are reflected live without
+having to restart the server.
 
 ```console
-npm run build
+npm i
+npm run start
 ```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
diff --git a/website/docs/introduction.md b/website/docs/introduction.md
@@ -5,26 +5,31 @@ sidebar_label: Introduction
 slug: /
 ---
 
-A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin.
-Consisting of 4 packages with more to be added in the future, the jellyfish project allow DeFiChain developers to build decentralized apps that are modern, easy to use and easy to test.
+## What is Jellyfish?
 
-Jellyfish follows a monorepo methodology, all maintained packages are in the same repo and published with the same version tag.
+A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized 
+finance on Bitcoin. Consisting of multiple packages with more to be added in the future, this JS library enable 
+developers to develop decentralized applications on top of DeFi Blockchain that are modern, easy to use and easy to 
+test.
 
-## Packages
+Written in TypeScript, jellyfish provides first-class citizen support for TypeScript with strongly typed interfaces of
+DeFi blockchain rpc exchanges. Built using modern JavaScript approaches, it emphasises a **future-first developer experience**
+and backport for compatibility. The protocol-agnostic core enable independent communication protocols, allowing
+vendor-agnostic middleware adaptable to any needs.
 
-* `@defichain/jellyfish` bundled usage entrypoint with conventional defaults for 4 bundles: umd, esm, cjs
-  and d.ts
-* `@defichain/jellyfish-api-core` is a protocol agnostic DeFiChain client interfaces, with a "foreign function interface"
-  design.
-* `@defichain/jellyfish-api-jsonrpc` implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification.
-* `@defichain/testcontainers` provides a lightweight, throw away instances for DeFiD node provisioned automatically in
-  Docker container.
+### Monorepo & packages 
 
-### Latest releases
+As with all modern JavaScript projects, jellyfish follows a monorepo structure with its concerns separated. All packages
+maintained in this repo are published with the same version tag and follows the `DeFiCh/ain` releases.
 
-|package|@latest|@next|
-|---|---|---|
-|`@defichain/jellyfish`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)|
-|`@defichain/jellyfish-api-core`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-api-core)](https://www.npmjs.com/package/@defichain/jellyfish-api-core/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-api-core/next)](https://www.npmjs.com/package/@defichain/jellyfish-api-core/v/next)|
-|`@defichain/jellyfish-api-jsonrpc`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-api-jsonrpc)](https://www.npmjs.com/package/@defichain/jellyfish-api-jsonrpc/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-api-jsonrpc/next)](https://www.npmjs.com/package/@defichain/jellyfish-api-jsonrpc/v/next)|
-|`@defichain/testcontainers`|[![npm](https://img.shields.io/npm/v/@defichain/testcontainers)](https://www.npmjs.com/package/@defichain/testcontainers/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/testcontainers/next)](https://www.npmjs.com/package/@defichain/testcontainers/v/next)|
+[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)
+[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)
+
+Package                                            | Description 
+---------------------------------------------------|-------------
+`@defichain/jellyfish`                             | Library bundled usage entrypoint with conventional defaults for 4 bundles: umd, esm, cjs and d.ts
+`@defichain/jellyfish-api-core`                    | A protocol agnostic DeFi Blockchain client interfaces, with a "foreign function interface" design.
+`@defichain/jellyfish-api-jsonrpc`                 | Implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification.
+`@defichain/jellyfish-json`                        | Allows parsing of JSON with 'lossless', 'bignumber' and 'number' numeric precision.
+`@defichain/jellyfish-network`                     | Contains DeFi blockchain various network configuration for main, net and regtest.
+`@defichain/testcontainers`                        | Provides a lightweight, throw away instances for DeFiD node provisioned automatically in a Docker container.
diff --git a/website/docs/jellyfish/api/mining.md b/website/docs/jellyfish/api/mining.md
@@ -5,21 +5,37 @@ sidebar_label: Mining API
 slug: /jellyfish/api/mining
 ---
 
+```js
+import {Client} from '@defichain/jellyfish'
+const client = new Client()
+
+// Using client.mining.
+const something = await client.mining.method()
+```
+
+
 ## getNetworkHashPerSecond
 
 Returns the estimated network hashes per second.
 - `nblocks` to estimate since last difficulty change.
 - `height` to estimate at the time of the given height.
 
-```ts
-getNetworkHashPerSecond (nblocks: number = 120, height: number = -1): Promise<number>
+```ts title="client.mining.getNetworkHashPerSecond()"
+interface mining {
+  getNetworkHashPerSecond (nblocks: number = 120, 
+                           height: number = -1): Promise<number>
+}
 ```
 
 ## getMintingInfo
 
 Get minting-related information.
 
-```ts
+```ts title="client.mining.getMintingInfo()"
+interface mining {
+  getMintingInfo (): Promise<MintingInfo>
+}
+
 interface MintingInfo {
   blocks: number
   currentblockweight?: number
@@ -36,6 +52,4 @@ interface MintingInfo {
   chain: 'main' | 'test' | 'regtest' | string
   warnings: string
 }
-
-getMintingInfo (): Promise<MintingInfo>
 ```
diff --git a/website/docs/jellyfish/api/wallet.md b/website/docs/jellyfish/api/wallet.md
@@ -5,13 +5,24 @@ sidebar_label: Wallet API
 slug: /jellyfish/api/wallet
 ---
 
+```js
+import {Client} from '@defichain/jellyfish'
+const client = new Client()
+
+// Using client.wallet.
+const something = await client.wallet.method()
+```
+
 ## getBalance
 
 Returns the total available balance in wallet.
 - `minimumConfirmation` to include transactions confirmed at least this many times.
 - `includeWatchOnly` for watch-only wallets, otherwise
   - Include balance in watch-only addresses (see `importAddress`)
 
-```ts
-getBalance (minimumConfirmation: number = 0, includeWatchOnly: boolean = false): Promise<BigNumber>
+```ts title="client.wallet.getBalance()"
+interface wallet {
+  getBalance (minimumConfirmation: number = 0, 
+              includeWatchOnly: boolean = false): Promise<BigNumber>   
+}
 ```
diff --git a/website/docs/jellyfish/design.md b/website/docs/jellyfish/design.md
@@ -1,7 +1,7 @@
 ---
 id: design
-title: Design
-sidebar_label: Design
+title: Jellyfish design
+sidebar_label: Jellyfish design
 slug: /jellyfish/design
 ---
 
@@ -47,7 +47,7 @@ it('lost precision converting DFI 😥', () => {
 });
 ```
 
-### `JellyfishJSON`
+### JellyfishJSON
 
 **api-core** implements `JellyfishJSON` that allows parsing of JSON with `'lossless'`, `'bignumber'` and 
 `'number'` numeric precision.
@@ -62,7 +62,7 @@ As not all number parsed are significant in all context, (e.g. `mining.getMintin
 users to use the `number` for non precision sensitive operation (e.g. `networkhashps`) and BigNumber for precision 
 sensitive operations.
 
-### `ApiClient`
+### ApiClient
 
 As jellyfish is written in TypeScript, all RPC exchanges with a node are typed. BigNumber precision is used for all 
 wallet or transaction related operations. While IEEE-754 number is used for all other arbitrary operations.

diff --git a/website/docs/jellyfish/overview.md b/website/docs/jellyfish/overview.md
diff --git a/website/docs/jellyfish/usage.md b/website/docs/jellyfish/usage.md
@@ -1,11 +1,11 @@
 ---
 id: usage
-title: Usage
-sidebar_label: Usage
+title: Jellyfish usage
+sidebar_label: Jellyfish usage
 slug: /jellyfish/usage
 ---
 
-## `@defichain/jellyfish`
+## @defichain/jellyfish
 
 ### Installation