Improve docs for abi required-ness (#3137)

* Improve docs for abi required-ness

* Newsfragment

* Fix list syntax

* Update parameters and types for Contract API

* Fill in parameters where possible

* Fix space in solidity docs link

* Fix doc syntax

docs/web3.contract.rst

@@ -35,7 +35,13 @@ After ``py-solc-x`` is installed, you will need to install a version of ``solc``
     >>> from solcx import install_solc
     >>> install_solc(version='latest')
 
-You should now be set up to run the contract deployment example below:
+You should now be set up to compile and deploy a contract.
+
+The following example runs through these steps:
+#. Compile Solidity contract into bytecode and an ABI
+#. Initialize a Contract Web3.py instance
+#. Deploy the contract using the Contract instance to initiate a transaction
+#. Interact with the contract functions using the Contract instance
 
 .. code-block:: python
 
@@ -132,7 +138,11 @@ Each Contract Factory exposes the following properties.
 
 .. py:attribute:: Contract.abi
 
-    The contract ABI array.
+    The contract ``abi``, or Application Binary Interface, specifies how a contract can
+    be interacted with. Without an ``abi``, the contract cannot be decoded. The ``abi``
+    enables the Contract instance to expose functions and events as object properties.
+
+    For further details, see the `Solidity ABI specification <https://docs.soliditylang.org/en/develop/abi-spec.html>`_.
 
 
 .. py:attribute:: Contract.bytecode
@@ -1280,3 +1290,9 @@ You can interact with web3.py contract API as follows:
 
    >>> deployed_contract.functions.retrieve().call()
    '0x0000000000000000000000000000000000000002'
+
+
+Where can I find more information about Ethereum Contracts?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comprehensive documentation for Contracts is available from the `Solidity Docs <https://docs.soliditylang.org/>`_.

docs/web3.eth.rst

@@ -1282,22 +1282,28 @@ Contracts
 
     The following arguments are accepted for contract class creation.
 
-    - ``abi``
-    - ``asm``
-    - ``ast``
-    - ``bytecode``
-    - ``bytecode_runtime``
-    - ``clone_bin``
-    - ``dev_doc``
-    - ``decode_tuples``
-    - ``interface``
-    - ``metadata``
-    - ``opcodes``
-    - ``src_map``
-    - ``src_map_runtime``
-    - ``user_doc``
-
-    See :doc:`web3.contract` for more information about how to use contracts.
+    :param abi: Application Binary Interface. Usually provided since an ``abi`` is required to interact with any contract.
+    :type abi: ABI
+    :param asm: Asssembly code generated by the compiler
+    :param ast: Abstract Syntax Tree of the contract generated by the compiler
+    :param bytecode: Bytecode of the contract generated by the compiler
+    :param bytecode_runtime: Bytecode stored at the contract address, excludes the constructor and initialization code
+    :param clone_bin:
+    :param dev_doc:
+    :param decode_tuples: Optionally convert tuples/structs to named tuples
+    :param interface:
+    :param metadata: Contract Metadata generated by the compiler
+    :param opcodes: Opcodes for the contract generated by the compiler
+    :param src_map:
+    :param src_map_runtime:
+    :param user_doc:
+    :return: Instance of the contract
+    :rtype: Contract
+    :raises TypeError: If the address is not provided
+    :raises AttributeError: If the contract class is not initialized
+
+    See the :doc:`web3.contract` documentation for more information about Contracts.
+
 
 .. py:method:: Eth.set_contract_factory(contractFactoryClass)
 

newsfragments/2539.internal.rst

@@ -0,0 +1 @@
+Additional contract ``abi`` documentation to make it a clear requirement for contract instances.