Merge pull request #588 from EOSIO/docs/starter

eosjs content plan 👍

docs.json

@@ -0,0 +1,46 @@
+{
+	"name": "eosjs",
+	"generators": [
+    {
+			"name": "collate_markdown",
+			"options": {
+				"docs_dir": "docs"
+			}
+		},
+		{
+			"name": "typedoc",
+			"options": {
+        "theme": "markdown",
+        "exclude": ["**/index*","**/*.test.ts","**/rpc-web*"],
+        "ignoreCompilerErrors": true,
+        "includeDeclarations": false,
+        "excludeExternals": true,
+        "excludeProtected": true,
+        "excludePrivate": true,
+        "typescript": {
+          "include": [
+            "src/**/*.js"
+          ]
+        }
+      }
+		}
+	],
+  "filters": [
+    {
+      "name": "search_replace",
+      "options": {
+        "search": "numeric.md#",
+        "replace": "#",
+        "filepattern": "numeric.md"
+      }
+    },
+    {
+      "name": "search_replace",
+      "options": {
+        "search": "serialize.md#",
+        "replace": "#",
+        "filepattern": "serialize.md"
+      }
+    }
+  ]
+}

docs/00_introduction.md

@@ -0,0 +1,8 @@
+`eosjs` is a Javascript library which provides an API for integrating with EOSIO-based blockchains using the [EOSIO Nodeos RPC API](https://developers.eos.io/eosio-nodeos/reference).  The documentation for `eosjs` is structured in the following way:
+
+* [Installation](02_installation.md) explains how to install `eosjs` using `npm` or `yarn`.
+* [Basic Usage](basic-usage/) provides information related to importing `eosjs` in various Javascript environments.  The [basic-usage](basic-usage/03_basic-usage.md) document specifically provides brief explanations of the components provided by `eosjs` as well as their typical use cases.
+* [FAQ](faq/) provides answers to frequently asked questions surrounding the `eosjs` software.
+* [How-To Guides](how-to-guides/) provides how-tos on everything from getting block information to proposing and signing multi-sig transactions.
+* [Troubleshooting](troubleshooting/) provides possible exceptions encountered when developing with `eosjs` and their most common causes.
+* [Technical Overview](01_technical-overview.md) provides a high-level overview of how `eosjs` works.

docs/01_technical-overview.md

@@ -0,0 +1,23 @@
+As stated in the [introduction](00_introduction.md), `eosjs` integrates with EOSIO-based blockchains using the [EOSIO Nodeos RPC API](https://developers.eos.io/eosio-nodeos/reference).
+
+In general, there are two objects that are used to interact with a blockchain via `eosjs`: the `JsonRpc` object, and the `Api` object.
+
+## JsonRpc
+The `JsonRpc` object is typically used when signing is not necessary.  Some examples include [getting block information](how-to-guides/00_how-to-get-block-information.md), [getting transaction information](how-to-guides/02_how-to-get-transaction-information.md), or [getting table information](how-to-guides/09_how-to-get-table-information.md).  
+
+The requests made by the `JsonRpc` object will either use a built-in `fetch` library, or [the `fetch` library passed in by the user](basic-usage/01_commonjs.md) to issue requests to the endpoint specified when instantiating the `JsonRpc` object.  When the various methods ([get_abi](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L66), [get_account](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L71), [get_block_header_state](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L76), etc) of the `JsonRpc` object are invoked, the calls are delegated to the `JsonRpc` object's [fetch function](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L42-L63), which in turn, delegate the requests to the `fetch` library.
+
+## Api
+The `Api` object is typically used when transacting on an EOSIO-based blockchain.  Some examples include [staking](how-to-guides/03_how-to-stake.md), [creating an account](how-to-guides/05_how-to-create-an-account.md), or [proposing multi-sig transactions](how-to-guides/13_how-to-propose-a-multisig-transaction.md).
+
+The typical use of the `Api` object is to call its [`transact` method](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-api.ts#L214-L254).  This method performs a number of steps depending on the input passed to it:
+
+* The `transact` method first checks if the **chainId** was set in the `Api` constructor, and if not, uses the [`JsonRpc` object's](#jsonrpc) [`get_info`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L101) method to retrieve the **chainId**.  
+* The `transact` method then checks if the `blocksBehind` and `expiration` fields are set and well-formed in the [optional configuration object, as specified in *How to Submit a Transaction*](how-to-guides/01_how-to-submit-a-transaction.md#).  
+    * If so, the block *blocksBehind* the head block retrieved from [`JsonRpc`'s `get_info`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L101) is set as the reference block and the transaction header is serialized using this reference block and the `expiration` field.
+* The `transact` method then checks if the appropriate TAPOS fields are present in the transaction ([they can either be specified directly in the transaction or in the optional configuration object](how-to-guides/01_how-to-submit-a-transaction.md#)) and throws an Error if not.
+* The necessary `abi`s for a transaction are then retrieved for the case when `transact` is expected to sign the transaction.
+* The `actions` are serialized using the `eosjs-serialize` `ser` object.
+* The entire transaction is then [serialized](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-api.ts#L154-L166), also using the `eosjs-serialize` `ser` object.
+* The transaction is then optionally signed, using the `signatureProvider`, the previously retrieved `abi`s, the private keys of the `signatureProvider`, and the `chainId`.
+* The transaction is then optionally broadcasted using `JsonRpc`'s [`push_transaction`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L187).

docs/02_installation.md

@@ -0,0 +1,9 @@
+`eosjs` can be installed via [`yarn`](https://yarnpkg.com/en/)
+```javascript
+yarn add eosjs
+```
+
+or [`npm`](https://www.npmjs.com/)
+```javascript
+npm install eosjs
+```