Update guides (#174)

* Update guides

Author: marekkirejczyk

docs/source/core.rst

@@ -106,7 +106,7 @@ A syntax sugar for `useChainCall`_ that uses ABI, function name, and arguments i
 - ``any[] | undefined`` - the result of a call or undefined if call didn't return yet
 
 useContractCalls
-===============
+================
 Makes calls to specific contracts and returns values. The hook will cause the component to refresh when a new block is mined and the return values change.
 A syntax sugar for `useChainCalls`_ that uses ABI, function name, and arguments instead of raw data.
 
@@ -253,7 +253,7 @@ Returns a balance of a given token for a given address.
   )
 
 useTokenAllowance
-===============
+=================
 
 Returns allowance (tokens left to use by spender) for given tokenOwner - spender relationship.
 
@@ -518,7 +518,7 @@ Returns short representation of address or throws an error if address is incorre
   // TypeError("Invalid input, address can't be parsed")
 
 shortenIfAddress
-==============
+================
 
 Returns short representation of address or throws an error if address is incorrent.
 Returns empty string if no address is provided.

docs/source/guide.rst

@@ -3,27 +3,130 @@ Guides
 
 Connecting to network
 *********************
-Coming soon...
+
+Read-only
+=========
+To connect to the network in read-only mode, provide ``readOnlyChainId`` and ``readOnlyUrls`` fileds in application configuration.
+
+See example configuration below:
+
+.. code-block:: javascript
+ 
+  const config = {
+    readOnlyChainId: ChainId.Mainnet,
+    readOnlyUrls: {
+      [ChainId.Mainnet]: 'https://mainnet.infura.io/v3/62687d1a985d4508b2b7a24827551934',
+    },
+  } 
+
+
+Browser wallet
+==============
+
+To connect to a wallet in a web3-enabled browser, use ``activateBrowserWallet`` returned by ``useEthers()``. 
+Once connected ``account`` variable will be availabe.
+
+See example below:
+
+.. code-block:: javascript
+
+  export function App() {
+    const { activateBrowserWallet, account } = useEthers()
+    return (
+      <div>
+        {!account && <button onClick={activateBrowserWallet}> Connect </button>}
+        {account && <p>Account: {account}</p>}
+      </div>
+    )
+  }
+
+
+useEthers
+=========
+
+``useEthers`` hook returns a number of useful functions and variables, see below:
+
+- ``account`` - current user account (or ``null`` if not connected or connected in read-only mode)
+
+- ``chainId`` - current chainId (or ``undefined`` if not connected)
+
+- ``library`` - an instance of ethers `Web3Provider <https://docs.ethers.io/v5/api/providers/other/#Web3Provider>`_ (or ``undefined`` if not connected). Read more about ethers providers `here <https://docs.ethers.io/v5/api/providers/>`_.
+
+- ``active`` - boolean that indicates if provider is connected (read or write mode)
+
+- ``activate`` - function that allows to connect to a wallet. This is a `web3-react <https://github.com/NoahZinsmeister/web3-react>`_ function that can take various connectors.
+
+- ``deactivate`` - function that disconnects wallet
+
+- ``error`` - an error that occurred during connecting (e.g. connection is broken, unsupported network)
+
+
+
+Example
+=======
+
+Example below demonstrates how to manage and use connection.
+
+Application allow to see the balance of Ethereum 2.0 staking contracts in read-only mode.
+When wallet is connected additionaly it shows user's account along with it's balance.
+
+Example is available `here <https://example.usedapp.io/balance>`_.
+
+.. code-block:: javascript
+
+  const config = {
+    readOnlyChainId: ChainId.Mainnet,
+    readOnlyUrls: {
+      [ChainId.Mainnet]: 'https://mainnet.infura.io/v3/62687d1a985d4508b2b7a24827551934',
+    },
+  }
+
+  ReactDOM.render(
+    <DAppProvider config={config}>
+      <App />
+    </DAppProvider>
+    document.getElementById('root')
+  )
+
+  const STAKING_CONTRACT = '0x00000000219ab540356cBB839Cbe05303d7705Fa'
+
+  export function App() {
+    const { activateBrowserWallet, deactivate, account } = useEthers()
+    const userBalance = useEtherBalance(account)
+    const stakingBalance = useEtherBalance(STAKING_CONTRACT)
+
+    return (
+      <div>
+        {!account && <button onClick={activateBrowserWallet}> Connect </button>}
+        {account && <button onClick={deactivate}> Disconnect </button>}
+      
+        {stakingBalance && <p>ETH2 staking balance: {formatEther(stakingBalance)} ETH </p>}
+        {account && <p>Account: {account}</p>}
+        {userBalance && <p>Ether balance: {formatEther(userBalance)} ETH </p>}
+      </div>
+    )
+  }
+
+
 
 Reading from blockchain
 ***********************
 
-When using hooks based on `useChainCall`, `useChainCalls` and `useContractCalls` there are important considerations;
+There is a number of useful hooks that you can use to read blockchain state:
 
-Avoid using the result of one hook in another
-==================================================
+- ``useBlockMeta()`` - return meta information (``timestamp`` and ``difficulty``) about most recent block mined
+- ``useEtherBalance(address)`` - returns ether balance as BigNumber for given address (or ``undefined``)
+- ``useTokenBalance(tokenAddress, address)``- returns balance of a given token as BigNumber for given address (or undefined)
+- ``useTokenAllowance(tokenAddress, ownerAddress, spenderAddress)`` - returns allowance of a given token as BigNumber for given owner and spender address pair (or undefined)
+
+Sooner or later you will want to make a custom call to a smart contract. Use ``useContractCall`` and ``useContractCalls`` for that purpose.
+See section below on creating custom hooks.
 
-Avoid using the result of one hook in another.
-This will break single multicall into multiple multicalls.
-It will reduce performance, generate delays, and flickering for the user.
-Instead, try to retrieve needed information in a single call or multiple parallel calls.
-That might need to modify smart contracts.
-If that is too complex consider using a custom backend or The Graph.
 
 Custom hooks
 ************
 
-Creating a custom hook with the use of our core hooks is straightforward, as an example let's write a *useTokenBalance* hook.
+Creating a custom hook with the use of our core hooks is straightforward, for example let’s examine the *useTokenBalance* hook.
 
 The hook will retrieve a balance of an ERC20 token of the provided address.
 
@@ -39,7 +142,7 @@ The hook will retrieve a balance of an ERC20 token of the provided address.
     return tokenBalance
   }
 
-Another example is useTokenAllowance hook. Instead of balanceOf we use allowance on ERC20 interface.
+Another example is useTokenAllowance hook. Instead of balanceOf, we use allowance on ERC20 interface.
 
 .. code-block:: javascript
 
@@ -69,13 +172,26 @@ The results are deferred so that the hook does not update too frequently.
 In our custom hooks we can use any standard react hooks, custom react hooks and useDApp hooks.
 Rules of hooks apply.
 
-All core hooks are available `here <https://github.com/EthWorks/useDapp/tree/master/packages/core/src/hooks>`_.
+Documentation for hooks is available `here <file:///Users/marek/Projects/useDapp/docs/dist/html/core.html#hooks>`_.
+
+
+Using hooks considerations
+==========================
+
+There are some important considerations when using hooks based on `useChainCall`, `useChainCalls` and `useContractCalls`.
+
+Avoid using the result of one hook in another.
+This will break single multicall into multiple multicalls.
+It will reduce performance, generate delays, and flickering for the user.
+Instead, try to retrieve needed information in a single call or multiple parallel calls.
+That might require modification of smart contracts.
+If that is too complex consider using a custom backend or `The Graph <https://thegraph.com/>`_.
 
 
 Testing hooks
 *************
 
-Let's take useTokenAllowance as an example.
+Let's take ``useTokenAllowance`` as an example.
 
 To write a test, start with a setup code that will create a mock provider and test wallets.
 
@@ -84,7 +200,7 @@ To write a test, start with a setup code that will create a mock provider and te
   const mockProvider = new MockProvider()
   const [deployer, spender] = mockProvider.getWallets()
 
-Before each test deploy an ERC20 contract. It's important as otherwise the result of one 
+Before each test, deploy an ERC20 contract. It's important as otherwise the result of one 
 test could break the other one.
 
 .. code-block:: javascript
@@ -113,15 +229,15 @@ After setup, we have to test the hook.
   expect(result.error).to.be.undefined
   expect(result.current).to.eq(utils.parseEther('1'))
 
-To check if the hook reads data correctly we need to prepare it first. We approve the spender so that we can check that our hook returns the correct value.
+To check if the hook reads data correctly, we need to prepare it first. We approve the spender so that we can check if our hook returns the correct value.
 
-To test the hook we need to render it using renderWeb3Hook. It works like `renderHook` from the react-testing-library,
+To test the hook we need to render it using ``renderWeb3Hook``. It works like ``renderHook`` from the `react-testing-library <https://testing-library.com/docs/react-testing-library/intro/>`_,
 but it wraps the hook into additional providers.
 
 React components update asynchronically. Reading data from the blockchain is also an async operation.
-To get the return value from the hook, wait for the result to be set. 
+To get the return value from the hook, wait for the result to be set. You can do it with ``waitForCurrent``.
 
-Then we can check if our result is correct. `result.current` is a value returned from our hook. It should be equal to 1 Ether.
+Then we can check if our result is correct. ``result.current`` is a value returned from our hook. It should be equal to 1 Ether.
 
 
 **Full example**