Merge pull request ethereum#930 from bartleyg/provider-docs-updates

Add documentation for gethdev and infura autoprovider shortcuts

Author: carver

Diff for: docs/middleware.rst

@@ -322,15 +322,27 @@ Geth-style Proof of Authority
 
 This middleware is required to connect to ``geth --dev`` or the Rinkeby public network.
 
-For example, to connect to a local ``geth --dev`` instance on Linux:
+The easiest way to connect to a default ``geth --dev`` instance which loads the middleware is:
+
+
+.. code-block:: python
+
+    >>> from web3.auto.gethdev import w3
+
+    # confirm that the connection succeeded
+    >>> w3.version.node
+    'Geth/v1.7.3-stable-4bb3c89d/linux-amd64/go1.9'
+
+This example connects to a local ``geth --dev`` instance on Linux with a
+unique IPC location and loads the middleware:
 
 
 .. code-block:: python
 
     >>> from web3 import Web3, IPCProvider
 
-    # connect to the default geth --dev IPC location
-    >>> w3 = Web3(IPCProvider('/tmp/geth.ipc'))
+    # connect to the IPC location started with 'geth --dev --datadir ~/mynode'
+    >>> w3 = Web3(IPCProvider('~/mynode/geth.ipc'))
 
     >>> from web3.middleware import geth_poa_middleware
 

Diff for: docs/providers.rst

@@ -145,8 +145,45 @@ Valid formats for the this environment variable are:
 - ``file:///path/to/node/rpc-json/file.ipc``
 - ``http://192.168.1.2:8545``
 - ``https://node.ontheweb.com``
+- ``ws://127.0.0.1:8546``
 
 
+Auto-initialization Provider Shortcuts
+--------------------------------------
+
+There are a couple auto-initialization shortcuts for common providers.
+
+Infura Mainnet
+~~~~~~~~~~~~~~
+
+To easily connect to the Infura Mainnet remote node, first register for a free
+API key if you don't have one at https://infura.io/signup .
+
+Then set the environment variable ``INFURA_API_KEY`` with your API key::
+
+    $ export INFURA_API_KEY=YourApiKey
+
+.. code-block:: python
+
+    >>> from web3.auto.infura import w3
+    
+    # confirm that the connection succeeded
+    >>> w3.isConnected()
+    True
+
+Geth dev Proof of Authority
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To connect to a ``geth --dev`` Proof of Authority instance with defaults:
+
+.. code-block:: python
+
+    >>> from web3.auto.gethdev import w3
+    
+    # confirm that the connection succeeded
+    >>> w3.isConnected()
+    True
+
 Built In Providers
 ------------------
 
@@ -171,7 +208,7 @@ HTTPProvider
     .. code-block:: python
 
         >>> from web3 import Web3
-        >>> web3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545")
+        >>> web3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545"))
 
     Note that you should create only one HTTPProvider per python
     process, as the HTTPProvider recycles underlying TCP/IP network connections,
@@ -236,7 +273,7 @@ WebsocketProvider
     .. code-block:: python
 
         >>> from web3 import Web3
-        >>> web3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546")
+        >>> web3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546"))
 
     Under the hood, the ``WebsocketProvider`` uses the python websockets library for
     making requests.  If you would like to modify how requests are made, you can