chore(Docs): new docs (#370)

* Started reworking Docs * improved table of content * issue with anchors * issue with anchors * More docs + more standalone examples * more consistency and new TOC * fix issues link * Started reworking Docs * improved table of content * issue with anchors * issue with anchors * More docs + more standalone examples * more consistency and new TOC * fix issues link * docs(SDK Docs): Updated SDK Docs including Quick Start and Examples Closes #340 * started reworking docs as per https://hackmd.aepps.com/s/rygc6uZp4 * restructure existing docs as per https://hackmd.aepps.com/s/rygc6uZp4 * adjust releasing instructions * more Docs restructuring according to https://hackmd.aepps.com/s/rygc6uZp4 * splitted guides into more files * removed emojis to allow anchor links in github * making it pretty * typo * typos * auto-generated docs for NodeJS Examples in new folder * updated examples, examples doc and needed deps * copy correct lock file for CI * update node on CI * testing node 11-slim after 12-slim failed * updating package.json an all lock files * Revert node version for CI
aeternity · Jun 12, 2019 · 9e17863 · 9e17863
1 parent a1494fd
commit 9e17863
Show file tree

Hide file tree

Showing 90 changed files with 5,544 additions and 5,953 deletions.
diff --git a/Dockerfile.ci b/Dockerfile.ci
@@ -6,7 +6,7 @@ FROM node:10.12.0
 USER root
 
 RUN curl -L https://github.com/docker/compose/releases/download/1.22.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
-COPY package.json shrinkwrap.yaml /
+COPY package.json package-lock.json pnpm-lock.yaml /
 RUN npm install
 RUN ln -f -s /node_modules/.bin/* /usr/local/bin/
 WORKDIR /app
diff --git a/README.md b/README.md
@@ -1,135 +1,98 @@
-# aepp-sdk
+# [Æternity](https://aeternity.com/)'s Javascript SDK
 
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 [![Build Status](https://ci.aepps.com/buildStatus/icon?job=aepp-sdk-js/develop)](https://ci.aepps.com/job/aepp-sdk-js/job/develop/)
 [![npm](https://img.shields.io/npm/v/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)
 [![npm](https://img.shields.io/npm/l/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)
 
 JavaScript SDK for the revolutionary [æternity] blockchain, targeting the
-[æternity node] implementation.
+[æternity node] implementation. Aepp-sdk is [hosted on GitHub].
 
-aepp-sdk is [hosted on GitHub].
-
-![Concept Drawing of aepp-sdk][concept]
-
-[concept]: concept.png "Concept Drawing of aepp-sdk"
 [æternity]: https://aeternity.com/
 [æternity node]: https://github.com/aeternity/aeternity
 [hosted on GitHub]: https://github.com/aeternity/aepp-sdk-js
 
 #### Disclaimer
 
-This SDK is at an alpha stage where things easily can break. We aim to make our
-alpha releases as stable as possible. Neverless it should not be taken as
-production-ready. To catch up with the more edgy state of development please
+This SDK is in continuos development where things can easily break, especially if you're not an officially released version. We aim to make all our
+ releases as stable as possible, neverless it should not be taken as
+production-ready.
+
+To catch up with the more edgy state of development please
 check out the [develop branch].
 
 [develop branch]: https://github.com/aeternity/aepp-sdk-js/tree/develop
 
-## [Usage Documentation]
-
-1. Add the latest `@aeternity/aepp-sdk` release from npmjs.com to your project using one of these commands
+## Table of content
+- [Æternity's Javascript SDK](#%C3%A6ternitys-javascript-sdk)
+      - [Disclaimer](#disclaimer)
+  - [Table of content](#table-of-content)
+  - [Quick Start](#quick-start)
+    - [1. Install the SDK](#1-install-the-sdk)
+    - [2. Import (a chosen Flavor)](#2-import-a-chosen-flavor)
+    - [3. Create an Account and get some _AEs_](#3-create-an-account-and-get-some-aes)
+  - [Guides & Examples](#guides--examples)
+  - [CLI - Command Line Client](#cli---command-line-client)
+  - [Contributing](#contributing)
+  - [Change Log](#change-log)
+  - [License](#license)
+
+## Quick Start
+
+### 1. Install the SDK
+Add the latest `@aeternity/aepp-sdk` release from npmjs.com to your project using one of these commands
 
 ```bash
-pnpm i @aeternity/aepp-sdk
-# or
+# install using npm...or yarn or pnpm
 npm i @aeternity/aepp-sdk
-# or
-yarn add @aeternity/aepp-sdk
 ```
 
-**Note:** To install a _Pre-Release_ (latest `beta` or `alpha` version) using on the latest Node version, you have to install the package appending the `@next` tag reference.
+**Note:** To install a _Pre-Release_ (latest `beta` or `alpha` version) using on the latest Node version, you have to install the package appending the `@next` tag reference, or even use the `#` symbol and the Repo URL to install a version coming from a specific branch.
 ```bash
-pnpm i @aeternity/aepp-sdk@next
+# install the @next version of the SDK
 npm i @aeternity/aepp-sdk@next
-yarn add @aeternity/aepp-sdk@next
+
+# install the #develop version of the SDK
+npm i https://github.com/aeternity/aepp-sdk-js#develop
 ```
 
-> Hint: You can also add a development version from GitHub by dropping the `@` and
-> adding `#` and a branch name at the end, for example
-> `pnpm i aeternity/aepp-sdk#develop`.
+### 2. Import (a chosen Flavor)
 
-2. Import the right flavor. For this example with get the `Universal` flavor, which contains all the features of the SDK:
+Import the right [flavor](docs/usage.md). For this example with get the `Universal` flavor, which contains all the features of the SDK:
 
 ```js
-import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or any other flavor
+import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or other flavor
 ```
 
-3. Create an instance and interact with it
+### 3. Create an Account and get some _AEs_
+You can do many more things now, but you'll probably have to start by:
 
-```js
+1. Create an account using the [💻 CLI](#cli---command-line-client)
+2. Give yourself some initial _AEs_ using the [🚰 Faucet Aepp](https://faucet.aepps.com/)
+3. Enjoy building Aepps 🤓
 
-// Start the instance
-
-Ae({
-  url: 'https://sdk-testnet.aepps.com',
-  internalUrl: 'https://sdk-testnet.aepps.com',
-  keypair: { secretKey: 'A_PRIV_KEY', publicKey: 'A_PUB_ADDRESS' },
-  networkId: 'aet_ua' // or any other networkId your client should connect to
-}).then(ae => {
-
-  // Interacting with the blockchain client
-
-  // getting the latest block height
-  ae.height().then(height => {
-    // logs current height
-    console.log('height', height)
-  }).catch(e => {
-    // logs error
-    console.log(e)
-  })
-
-  // getting the balance of a public address
-  ae.balance('A_PUB_ADDRESS').then(balance => {
-    // logs current balance of "A_PUB_ADDRESS"
-    console.log('balance', balance)
-  }).catch(e => {
-    // logs error
-    console.log(e)
-  })
-})
-```
+## Guides & Examples
 
-4. **IMPORTANT:** 🤓 Check out the [Usage Documentation] to avoid common pitfalls!
+Check out our [Guides](docs/README.md) and [Examples](examples/README.md).
 
-[Usage Documentation]: docs/usage.md
+## CLI - Command Line Client
 
+To quickly test _all_ of Aeternity's blockchain features from your Terminal, you can Install and use our **NodeJS [CLI](https://github.com/aeternity/aepp-cli-js)** by running:
 
-> Remember: you can also "compose" your own flavor by mixing 2 or more flavors likes so:
+1. `npm i -g @aeternity/aepp-cli` to globally install the CLI
+2. `aecly --help` to get a list of possible commands
 
-```js
-import Wallet from '@aeternity/aepp-sdk/es/ae/wallet.js'
-import Contract from '@aeternity/aepp-sdk/es/ae/contract.js'
-import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory.js'
-
-// make a "mixed flavor" containing Wallet and Contracts flavors
-Wallet.compose(Contract)({
-            url: 'https://sdk-testnet.aepps.com',
-            internalUrl: 'https://sdk-testnet.aepps.com',
-            accounts: [MemoryAccount({keypair: {secretKey: account.priv, publicKey: account.pub}})],
-            address: account.pub,
-            onTx: true, // or a function to Guard the Rpc client
-            onChain: true, // or a function to Guard the Rpc client
-            onAccount: true, // or a function to Guard the Rpc client
-            networkId: 'ae_uat'
-          }).then(ae => {
-            // ae is your initialised client now! :)
-            // ...
-```
-## [Hacking]
+_eg._ Create an Account:
 
-For advanced use, development versions and to get a deeper understanding of the
-SDK, it is advised to read the [Hacking] documentation.
+`aecli account create testWhateverAccountName`
 
-[Hacking]: docs/hacking.md
+## Contributing
 
-## [API]
+For advanced use, to get a deeper understanding of the SDK or to contribute to its development, it is advised to read the [Contributing Guidelines](docs/contrib/README.md) section.
 
-[API]: docs/api.md
+## Change Log
 
-## [Change Log]
-
-[Change Log]: CHANGELOG.md
+We keep our [Changelog](CHANGELOG.md) up to date.
 
 ## License
 
@@ -147,3 +110,4 @@ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
 OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
 THIS SOFTWARE.
+
diff --git a/concept.png b/concept.png
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,46 @@
+# Guides
+
+## Intro
+There are three different ways of incorporating aepp-sdk-js into your project, depending on the particular scenario:
+* ES Modules at `es/` (recommended)
+* Node.js bundle at `dist/aepp-sdk.js`
+* Browser bundle at `dist/aepp-sdk.browser.js`
+
+Also, please be aware that using `require` instead of module loader syntax
+(`import`) means that the default export automatically becomes exposed as
+`default`, which is reflected below in the code examples. This is due to a
+recent change in [Babel] compilation and fully compliant with the standard.
+
+### Flavors / Entry Points
+
+The recommended approach to use aepp-sdk is to import one of the following _Ae
+Factories_ based on the specific use case:
+
+* [@aeternity/aepp-sdk/es/ae/wallet](api/ae/wallet.md): for **Wallet**'s focused development
+* [@aeternity/aepp-sdk/es/ae/contract](api/ae/contract.md): for **Contract**'s focused development
+* [@aeternity/aepp-sdk/es/ae/aepp](api/ae/aepp.md): for **Web Aepp**'s focused development ⚠️ **_No Wallet support_**
+* [@aeternity/aepp-sdk/es/ae/aens](api/ae/aens.md): for **AENs**' focused development
+* [@aeternity/aepp-sdk/es/ae/oracle](api/ae/oracle.md): for **Oracle**'s focused development
+* [@aeternity/aepp-sdk/es/ae/universal](api/ae/universal.md): for **Universal** development (includes all SDK features)
+
+In order to cater to more specific needs, it is recommended to refer to the
+[contributing Docs](contrib/README.md).
+
+### Testing Networks
+When initialising a client, to test, you can use Aeternity's Test Nework URLs:
+
+### Testnet (https://sdk-testnet.aepps.com)
+You can use this URL with any releasee on [npmjs](https://www.npmjs.com/package/@aeternity/aepp-sdk). It offers the last stable version of [Node](https://github.com/aeternity/aeternity), used by all of of Aeternity's Dev Tools.
+
+## Guides
+### Browser
+  - [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
+  - [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
+  - [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
+  - [Import SDK in **VueJS**](guides/import-vuejs.md)
+### NodeJS Environment
+  - [Import SDK in **NodeJS**](guides/import-nodejs.md)
+
+
+## Examples
+Check out our [Examples](../examples/README.md) for more.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -0,0 +1,2 @@
+# ⚠️ Disclaimer
+We're doing our best to keep the API documentation up to date, but [please let us know if you see some out-of-date file](https://github.com/aeternity/aepp-sdk-js/issues/new). Thanks!
diff --git a/docs/api/account.md b/docs/api/account.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/account
 Account module
 
+**Export**: Account  
 **Example**  
 ```js
 import Account from '@aeternity/aepp-sdk/es/account'

diff --git a/docs/api/account/memory.md b/docs/api/account/memory.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/account/memory
 Memory Account module
 
+**Export**: MemoryAccount  
 **Example**  
 ```js
 import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory'

diff --git a/docs/api/account/selector.md b/docs/api/account/selector.md
@@ -5,6 +5,7 @@ Accounts Selector module
 
 This is the complement to [@aeternity/aepp-sdk/es/accounts](#module_@aeternity/aepp-sdk/es/accounts).
 
+**Export**: Account  
 **Example**  
 ```js
 import Selector from '@aeternity/aepp-sdk/es/account/selector'

diff --git a/docs/api/accounts.md b/docs/api/accounts.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/accounts
 Accounts module
 
+**Export**: Accounts  
 **Example**  
 ```js
 import Accounts from '@aeternity/aepp-sdk/es/accounts'

diff --git a/docs/api/ae.md b/docs/api/ae.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/ae
 Ae module
 
+**Export**: Ae  
 **Example**  
 ```js
 import Ae from '@aeternity/aepp-sdk/es/ae'

diff --git a/docs/api/ae/aens.md b/docs/api/ae/aens.md
@@ -7,6 +7,7 @@ The high-level description of the naming system is
 https://github.com/aeternity/protocol/blob/master/AENS.md in the protocol
 repository.
 
+**Export**: Aens  
 **Example**  
 ```js
 import Aens from '@aeternity/aepp-sdk/es/ae/aens'

diff --git a/docs/api/ae/aepp.md b/docs/api/ae/aepp.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/ae/aepp
 Aepp module
 
+**Export**: Aepp  
 **Example**  
 ```js
 import Ae from '@aeternity/aepp-sdk/es/ae/aepp'

diff --git a/docs/api/ae/contract.md b/docs/api/ae/contract.md
@@ -6,6 +6,7 @@ Contract module - routines to interact with the æternity contract
 High level documentation of the contracts are available at
 https://github.com/aeternity/protocol/tree/master/contracts and
 
+**Export**: Contract  
 **Example**  
 ```js
 import Contract from '@aeternity/aepp-sdk/es/ae/contract' (Using tree-shaking)

diff --git a/docs/api/ae/oracle.md b/docs/api/ae/oracle.md
@@ -7,6 +7,7 @@ The high-level description of the oracle system is
 https://github.com/aeternity/protocol/blob/master/ORACLE.md in the protocol
 repository.
 
+**Export**: Oracle  
 **Example**  
 ```js
 import Oracle from '@aeternity/aepp-sdk/es/ae/oracle'

diff --git a/docs/api/ae/universal.md b/docs/api/ae/universal.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/ae/universal
 Universal module
 
+**Export**: Universal  
 **Example**  
 ```js
 import Ae from '@aeternity/aepp-sdk/es/ae/universal'

diff --git a/docs/api/ae/wallet.md b/docs/api/ae/wallet.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/ae/wallet
 Wallet module
 
+**Export**: Wallet  
 **Example**  
 ```js
 import Wallet from '@aeternity/aepp-sdk/es/ae/wallet'

diff --git a/docs/api/chain.md b/docs/api/chain.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/chain
 Chain module
 
+**Export**: Chain  
 **Example**  
 ```js
 import Chain from '@aeternity/aepp-sdk/es/chain'

diff --git a/docs/api/chain/node.md b/docs/api/chain/node.md
@@ -5,6 +5,7 @@ ChainNode module
 
 This is the complement to [@aeternity/aepp-sdk/es/chain](#module_@aeternity/aepp-sdk/es/chain).
 
+**Export**: ChainNode  
 **Example**  
 ```js
 import ChainNode from '@aeternity/aepp-sdk/es/chain/node'

diff --git a/docs/api/channel/index.md b/docs/api/channel/index.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/channel/index
 Channel module
 
+**Export**: Channel  
 **Example**  
 ```js
 import Channel from '@aeternity/aepp-sdk/es/channel/index'

diff --git a/docs/api/contract.md b/docs/api/contract.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/contract
 Contract Base module
 
+**Export**: Contract  
 **Example**  
 ```js
 import ContractBase from '@aeternity/aepp-sdk/es/contract'

diff --git a/docs/api/contract/aci.md b/docs/api/contract/aci.md
@@ -3,6 +3,7 @@
 ## @aeternity/aepp-sdk/es/contract/aci
 ContractACI module
 
+**Export**: ContractACI  
 **Example**  
 ```js
 import ContractACI from '@aeternity/aepp-sdk/es/contract/aci'
@@ -69,6 +70,8 @@ Generate contract ACI object with predefined js methods for contract usage
 | source | `String` | Contract source code |
 | [options] | `Object` | Options object |
 | [options.aci] | `Object` | Contract ACI |
+| [options.contractAddress] | `Object` | Contract address |
+| [options.opt] | `Object` | Contract options |
 
 **Example**  
 ```js

diff --git a/docs/api/contract/compiler.md b/docs/api/contract/compiler.md
@@ -5,6 +5,7 @@ ContractCompilerAPI module
 
 This is the complement to [@aeternity/aepp-sdk/es/contract](#module_@aeternity/aepp-sdk/es/contract).
 
+**Export**: ContractCompilerAPI  
 **Example**  
 ```js
 import ContractCompilerAPI from '@aeternity/aepp-sdk/es/contract/compiler'