improve Providers context docs; closes #1609

Author: wolovim

docs/index.rst

@@ -15,15 +15,15 @@ Contents
     quickstart
     overview
     node
+    providers
+    examples
+    troubleshooting
     v5_migration
     v4_migration
     filters
     contracts
-    providers
     ens_overview
     middleware
-    examples
-    troubleshooting
     web3.main
     web3.eth
     web3.eth.account

docs/quickstart.rst

@@ -35,9 +35,14 @@ Using Web3
 
 To use the web3 library you will need to initialize the
 :class:`~web3.Web3` class and connect to an Ethereum node.
-The quickest way to do so for free is by setting up an account on
-`Infura <https://infura.io/>`_. On Infura, create a project and copy
-the Project ID. Then set the environment variable ``WEB3_INFURA_PROJECT_ID``.
+There are several ways to configure this connection; the
+full details can be found in the :ref:`Providers<providers>`
+documentation.
+
+The quickest way to connect to a mainnet node for free is by setting up an
+account on `Infura <https://infura.io/>`_. On the Infura dashboard, create
+a project, copy the Project ID, then set the environment variable
+``WEB3_INFURA_PROJECT_ID`` before running your script or application.
 
 .. code-block:: shell
 

docs/troubleshooting.rst

@@ -38,6 +38,24 @@ Often, the best way to guarantee a correct environment is with ``virtualenv``, l
 
 .. _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
+
+    >>> w3.isConnected()
+    False
+
+There's a variety of explanations for why you may see ``False`` here. If you're
+running a local node, such as Geth, double-check that you've indeed started the
+binary and that you've started it from the intended directory - particularly if
+you've specified a relative path to its ipc file.
+
+If that does not address your issue, it's probable that you still have a
+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,

newsfragments/1609.doc.rst

@@ -0,0 +1 @@
+Improve documentation that introduces and troubleshoots Providers.