Clean up docs before publish

5 files changed, 69 insertions, 20 deletions

diff --git a/python-packages/order_utils/setup.py b/python-packages/order_utils/setup.py
index 01a6c7360..6f9465680 100755
--- a/python-packages/order_utils/setup.py
+++ b/python-packages/order_utils/setup.py
@@ -188,6 +188,7 @@ setup(
             "pylint",
             "pytest",
             "sphinx",
+            "sphinx-autodoc-typehints",
             "tox",
             "twine",
         ]
diff --git a/python-packages/order_utils/src/conf.py b/python-packages/order_utils/src/conf.py
index 6b6776d01..d8f56b29e 100644
--- a/python-packages/order_utils/src/conf.py
+++ b/python-packages/order_utils/src/conf.py
@@ -22,6 +22,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinx_autodoc_typehints",
 ]
 
 templates_path = ["doc_templates"]
diff --git a/python-packages/order_utils/src/index.rst b/python-packages/order_utils/src/index.rst
index 4d27a4b17..ce618c6ff 100644
--- a/python-packages/order_utils/src/index.rst
+++ b/python-packages/order_utils/src/index.rst
@@ -7,21 +7,27 @@ Python zero_ex.order_utils
    :maxdepth: 2
    :caption: Contents:
 
-.. autoclass:: zero_ex.order_utils.Order
+.. automodule:: zero_ex.order_utils
    :members:
 
-See source for class properties.  Sphinx does not easily generate class property docs; pull requests welcome.
+.. autoclass:: zero_ex.order_utils.Order
 
-.. automodule:: zero_ex.order_utils
-   :members:
+   See source for class properties.  Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome.
+
+zero_ex.order_utils.asset_data_utils
+------------------------------------
 
 .. automodule:: zero_ex.order_utils.asset_data_utils
    :members:
 
 .. autoclass:: zero_ex.order_utils.asset_data_utils.ERC20AssetData
 
+   See source for class properties.  Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome.
+
 .. autoclass:: zero_ex.order_utils.asset_data_utils.ERC721AssetData
 
+   See source for class properties.  Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome.
+
 Indices and tables
 ==================
 
diff --git a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py
index 4697ad99c..39d411507 100644
--- a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py
+++ b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py
@@ -1,13 +1,11 @@
 """Order utilities for 0x applications.
 
-Some methods require the caller to pass in a `Web3.HTTPProvider` object.  For
-local testing one may construct such a provider pointing at an instance of
+Some methods require the caller to pass in a `Web3.BaseProvider`:code: object.
+For local testing one may construct such a provider pointing at an instance of
 `ganache-cli <https://www.npmjs.com/package/ganache-cli>`_ which has the 0x
 contracts deployed on it.  For convenience, a docker container is provided for
-just this purpose.  To start it: ``docker run -d -p 8545:8545 0xorg/ganache-cli
---gasLimit 10000000 --db /snapshot --noVMErrorsOnRPCResponse -p 8545
---networkId 50 -m "concert load couple harbor equip island argue ramp clarify
-fence smart topic"``.
+just this purpose.  To start it:
+`docker run -d -p 8545:8545 0xorg/ganache-cli:2.2.2`:code:.
 """
 
 from copy import copy
@@ -85,17 +83,53 @@ class Order(TypedDict):  # pylint: disable=too-many-instance-attributes
     """A Web3-compatible representation of the Exchange.Order struct."""
 
     makerAddress: str
+    """Address that created the order."""
+
     takerAddress: str
+    """Address that is allowed to fill the order.
+
+    If set to 0, any address is allowed to fill the order.
+    """
+
     feeRecipientAddress: str
+    """Address that will recieve fees when order is filled."""
+
     senderAddress: str
+    """Address that is allowed to call Exchange contract methods that affect
+    this order. If set to 0, any address is allowed to call these methods.
+    """
+
     makerAssetAmount: int
+    """Amount of makerAsset being offered by maker. Must be greater than 0."""
+
     takerAssetAmount: int
+    """Amount of takerAsset being bid on by maker. Must be greater than 0."""
+
     makerFee: int
+    """Amount of ZRX paid to feeRecipient by maker when order is filled.  If
+    set to 0, no transfer of ZRX from maker to feeRecipient will be attempted.
+    """
+
     takerFee: int
+    """Amount of ZRX paid to feeRecipient by taker when order is filled.  If
+    set to 0, no transfer of ZRX from taker to feeRecipient will be attempted.
+    """
+
     expirationTimeSeconds: int
+    """Timestamp in seconds at which order expires."""
+
     salt: int
+    """Arbitrary number to facilitate uniqueness of the order's hash."""
+
     makerAssetData: bytes
+    """Encoded data that can be decoded by a specified proxy contract when
+    transferring makerAsset. The last byte references the id of this proxy.
+    """
+
     takerAssetData: bytes
+    """Encoded data that can be decoded by a specified proxy contract when
+    transferring takerAsset. The last byte references the id of this proxy.
+    """
 
 
 def make_empty_order() -> Order:
@@ -125,7 +159,7 @@ def order_to_jsdict(
 ) -> dict:
     """Convert a Web3-compatible order struct to a JSON-schema-compatible dict.
 
-    More specifically, do explicit decoding for the `bytes` fields.
+    More specifically, do explicit decoding for the `bytes`:code: fields.
 
     >>> import pprint
     >>> pprint.pprint(order_to_jsdict(
@@ -175,7 +209,7 @@ def order_to_jsdict(
 def jsdict_order_to_struct(jsdict: dict) -> Order:
     r"""Convert a JSON-schema-compatible dict order to a Web3-compatible struct.
 
-    More specifically, do explicit encoding of the `bytes` fields.
+    More specifically, do explicit encoding of the `bytes`:code: fields.
 
     >>> import pprint
     >>> pprint.pprint(jsdict_order_to_struct(
@@ -234,7 +268,7 @@ def generate_order_hash_hex(order: Order, exchange_address: str) -> str:
     :param order: The order to be hashed.  Must conform to `the 0x order JSON schema <https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/order_schema.json>`_.
     :param exchange_address: The address to which the 0x Exchange smart
         contract has been deployed.
-    :rtype: A string, of ASCII hex digits, representing the order hash.
+    :returns: A string, of ASCII hex digits, representing the order hash.
 
     >>> generate_order_hash_hex(
     ...     {
@@ -296,8 +330,13 @@ class OrderInfo(NamedTuple):
     """A Web3-compatible representation of the Exchange.OrderInfo struct."""
 
     order_status: str
+    """A `str`:code: describing the order's validity and fillability."""
+
     order_hash: bytes
+    """A `bytes`:code: object representing the EIP712 hash of the order."""
+
     order_taker_asset_filled_amount: int
+    """An `int`:code: indicating the amount that has already been filled."""
 
 
 def is_valid_signature(
@@ -305,15 +344,15 @@ def is_valid_signature(
 ) -> Tuple[bool, str]:
     """Check the validity of the supplied signature.
 
-    Check if the supplied ``signature`` corresponds to signing ``data`` with
-    the private key corresponding to ``signer_address``.
+    Check if the supplied `signature`:code: corresponds to signing `data`:code:
+    with the private key corresponding to `signer_address`:code:.
 
     :param provider: A Web3 provider able to access the 0x Exchange contract.
     :param data: The hex encoded data signed by the supplied signature.
     :param signature: The hex encoded signature.
     :param signer_address: The hex encoded address that signed the data to
         produce the supplied signature.
-    :rtype: Tuple consisting of a boolean and a string.  Boolean is true if
+    :returns: Tuple consisting of a boolean and a string.  Boolean is true if
         valid, false otherwise.  If false, the string describes the reason.
 
     >>> is_valid_signature(
@@ -428,8 +467,8 @@ def sign_hash(
     :param provider: A Web3 provider.
     :param signer_address: The address of the signing account.
     :param hash_hex: A hex string representing the hash, like that returned
-        from `generate_order_hash_hex()`.
-    :rtype: A string, of ASCII hex digits, representing the signature.
+        from `generate_order_hash_hex()`:code:.
+    :returns: A string, of ASCII hex digits, representing the signature.
 
     >>> provider = Web3.HTTPProvider("http://127.0.0.1:8545")
     >>> sign_hash(
diff --git a/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py b/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py
index fab7479d2..f8e9bc42b 100644
--- a/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py
+++ b/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py
@@ -17,6 +17,8 @@ class ERC20AssetData(TypedDict):
     """Object interface to ERC20 asset data."""
 
     asset_proxy_id: str
+    """asset proxy id"""
+
     token_address: str
 
 
@@ -32,7 +34,7 @@ def encode_erc20_asset_data(token_address: str) -> str:
     """Encode an ERC20 token address into an asset data string.
 
     :param token_address: the ERC20 token's contract address.
-    :rtype: hex encoded asset data string, usable in the makerAssetData or
+    :returns: hex encoded asset data string, usable in the makerAssetData or
         takerAssetData fields in a 0x order.
 
     >>> encode_erc20_asset_data('0x1dc4c1cefef38a777b15aa20260a54e584b16c48')
@@ -85,7 +87,7 @@ def encode_erc721_asset_data(token_address: str, token_id: int) -> str:
 
     :param token_address: the ERC721 token's contract address.
     :param token_id: the identifier of the asset's instance of the token.
-    :rtype: hex encoded asset data string, usable in the makerAssetData or
+    :returns: hex encoded asset data string, usable in the makerAssetData or
         takerAssetData fields in a 0x order.
 
     >>> encode_erc721_asset_data('0x1dc4c1cefef38a777b15aa20260a54e584b16c48', 1)