troubleshooting docs for instance configuration

docs/node.rst

@@ -4,7 +4,7 @@ Your Ethereum Node
 .. _why_need_connection:
 
 Why do I need to connect to a node?
---------------------------------------
+-----------------------------------
 
 The Ethereum protocol defines a way for people to interact with
 smart contracts and each other over a network.
@@ -19,7 +19,7 @@ not run its own node internally.
 .. _choosing_node:
 
 How do I choose which node to use?
---------------------------------------
+----------------------------------
 
 Due to the nature of Ethereum, this is largely a question of personal preference, but
 it has significant ramifications on security and usability. Further, node software is
@@ -71,7 +71,7 @@ Typically, you are choosing between the main network and one of the available te
 See :ref:`choosing_network`
 
 Can I use MetaMask as a node?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MetaMask is not a node. It is an interface for interacting with a node.
 Roughly, it's what you get if you turn Web3.py into a browser extension.
@@ -85,7 +85,7 @@ If you are trying to use accounts that were already created in MetaMask, see
 .. _choosing_network:
 
 Which network should I connect to?
-------------------------------------
+----------------------------------
 
 Once you have answered :ref:`choosing_node` you have to pick which network
 to connect to. This is easy for some scenarios: if you have ether and you want

docs/providers.rst

@@ -19,7 +19,7 @@ can skip the rest of the Providers section.
 .. _choosing_provider:
 
 Choosing How to Connect to Your Node
---------------------------------------
+------------------------------------
 
 Most nodes have a variety of ways to connect to them. If you have not
 decided what kind of node to use, head on over to :ref:`choosing_node`
@@ -190,7 +190,7 @@ an optional secret key, set the environment variable ``WEB3_INFURA_API_SECRET``:
     True
 
 Geth dev Proof of Authority
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To connect to a ``geth --dev`` Proof of Authority instance with defaults:
 

docs/troubleshooting.rst

@@ -1,10 +1,10 @@
 Troubleshooting
-=============================
+===============
 
 .. _setup_environment:
 
 Set up a clean environment
-----------------------------------------------
+--------------------------
 
 Many things can cause a broken environment. You might be on an unsupported version of Python.
 Another package might be installed that has a name or version conflict.
@@ -36,10 +36,36 @@ Often, the best way to guarantee a correct environment is with ``virtualenv``, l
 .. NOTE:: Remember that each new terminal session requires you to reactivate your virtualenv, like:
     ``$ source ~/.venv-py3/bin/activate``
 
+
+.. _instance_troubleshooting:
+
+Why can't I use a particular function?
+--------------------------------------
+
+Note that a Web3.py instance must be configured before you can use most of its capabilities.
+One symptom of not configuring the instance first is an error that looks something like this:
+``AttributeError: type object 'Web3' has no attribute 'eth'``.
+
+To properly configure your Web3.py instance, specify which provider you're using to connect to the
+Ethereum network. An example configuration, if you're connecting to a locally run node, might be:
+
+.. code-block:: python
+
+    >>> from web3 import Web3
+    >>> w3 = Web3(Web3.HTTPProvider('http://localhost:8545'))
+
+    # now `w3` is available to use:
+    >>> w3.isConnected()
+    True
+    >>> w3.eth.send_transaction(...)
+
+Refer to the :ref:`providers` documentation for further help with configuration.
+
+
 .. _use_metamask_accounts:
 
 Why isn't my web3 instance connecting to the network?
---------------------------------------------------------
+-----------------------------------------------------
 You can check that your instance is connected via the ``isConnected`` method:
 
 .. code-block:: python
@@ -57,7 +83,7 @@ Provider configuration issue. There are several options for configuring
 a Provider, detailed :ref:`here<providers>`.
 
 How do I use my MetaMask accounts from Web3.py?
---------------------------------------------------------
+-----------------------------------------------
 Often you don't need to do this, just make a new account in Web3.py,
 and transfer funds from your MetaMask account into it. But if you must...
 
@@ -71,7 +97,7 @@ and :ref:`eth-account`.
 .. _faucets:
 
 How do I get ether for my test network?
---------------------------------------------------------
+---------------------------------------
 
 Test networks usually have something called a "faucet" to
 help get test ether to people who want to use it. The faucet

newsfragments/1865.doc.rst

@@ -0,0 +1 @@
+Add instance configuration troubleshooting docs.