From 261bced822f771d5f93a6c5bc7e3e23242f0e652 Mon Sep 17 00:00:00 2001 From: "F. Eugene Aumson" Date: Wed, 8 Apr 2020 12:10:23 -0400 Subject: [PATCH 1/2] Fix redundant docstrings and unpin sphinx The latest version of Sphinx (documentation generation utility) was giving a warning (which we were configured to treat as an error) about there being multiple docstring definitions for the same class. This had never been flagged before. --- python-packages/contract_wrappers/setup.py | 2 +- python-packages/contract_wrappers/src/conf.py | 36 +++++++++++++++++++ .../contract_wrappers/src/index.rst | 23 ------------ python-packages/order_utils/src/index.rst | 10 ------ 4 files changed, 37 insertions(+), 34 deletions(-) diff --git a/python-packages/contract_wrappers/setup.py b/python-packages/contract_wrappers/setup.py index 0462ead4fb..08a6638d7d 100755 --- a/python-packages/contract_wrappers/setup.py +++ b/python-packages/contract_wrappers/setup.py @@ -225,7 +225,7 @@ setup( "pydocstyle", "pylint", "pytest", - "sphinx==2.4.4", # pinned because of https://github.com/sphinx-doc/sphinx/issues/7429 + "sphinx", "sphinx-autodoc-typehints", "tox", "twine", diff --git a/python-packages/contract_wrappers/src/conf.py b/python-packages/contract_wrappers/src/conf.py index 38c0695294..a041a9ffe4 100644 --- a/python-packages/contract_wrappers/src/conf.py +++ b/python-packages/contract_wrappers/src/conf.py @@ -54,3 +54,39 @@ htmlhelp_basename = "contract_wrapperspydoc" # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {"https://docs.python.org/": None} + + +def annotate_gend_tuple_docstring( # pylint: disable=too-many-arguments + app, # pylint: disable=unused-argument + what, # pylint: disable=unused-argument + name, # pylint: disable=unused-argument + obj, # pylint: disable=unused-argument + options, # pylint: disable=unused-argument + lines, +): + """Annotate docstrings of generated tuples.""" + docstring_extensions = { + "LibOrderOrder": [ + "This is the generated class representing `the Order struct `_." + ], + "LibFillResultsFillResults": [ + "This is the generated class representing `the FillResults struct `_." + ], + "LibFillResultsMatchedFillResults": [ + "This is the generated class representing `the MatchedFillResults struct `_." + ], + "LibOrderOrderInfo": [ + "This is the generated class representing `the OrderInfo struct `_." + ], + "LibZeroExTransactionZeroExTransaction": [ + "This is the generated class representing `the ZeroExTransaction struct `_." + ], + } + unqualified_name = name.split(".")[-1] + if unqualified_name in docstring_extensions: + lines.extend(docstring_extensions[unqualified_name]) + + +def setup(app): + """Install callbacks.""" + app.connect("autodoc-process-docstring", annotate_gend_tuple_docstring) diff --git a/python-packages/contract_wrappers/src/index.rst b/python-packages/contract_wrappers/src/index.rst index fada419b90..ef482bccd4 100644 --- a/python-packages/contract_wrappers/src/index.rst +++ b/python-packages/contract_wrappers/src/index.rst @@ -198,29 +198,6 @@ zero_ex.contract_wrappers.exchange.types .. autoclass:: zero_ex.contract_wrappers.exchange.types.ZeroExTransaction -zero_ex.contract_wrappers.exchange: Generated Tuples -==================================================== - -.. autoclass:: zero_ex.contract_wrappers.exchange.LibOrderOrder - - This is the generated class representing `the Order struct `_. - -.. autoclass:: zero_ex.contract_wrappers.exchange.LibFillResultsFillResults - - This is the generated class representing `the FillResults struct `_. - -.. autoclass:: zero_ex.contract_wrappers.exchange.LibFillResultsMatchedFillResults - - This is the generated class representing `the MatchedFillResults struct `_. - -.. autoclass:: zero_ex.contract_wrappers.exchange.LibOrderOrderInfo - - This is the generated class representing `the OrderInfo struct `_. - -.. autoclass:: zero_ex.contract_wrappers.exchange.LibZeroExTransactionZeroExTransaction - - This is the generated class representing `the ZeroExTransaction struct `_. - Indices and tables ================== diff --git a/python-packages/order_utils/src/index.rst b/python-packages/order_utils/src/index.rst index 1308f18c62..f2df2e3a93 100644 --- a/python-packages/order_utils/src/index.rst +++ b/python-packages/order_utils/src/index.rst @@ -16,16 +16,6 @@ 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 - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: zero_ex.order_utils.asset_data_utils.ERC721AssetData - :members: - :undoc-members: - :show-inheritance: - Indices and tables ================== From 6ddbea207f47a360f90795dad37bf022fad3426d Mon Sep 17 00:00:00 2001 From: "F. Eugene Aumson" Date: Wed, 8 Apr 2020 12:12:20 -0400 Subject: [PATCH 2/2] Stop using 3rd party sphinx typehints plugin Because sphinx itself supports typehints now, and a recent update to plugin caused it to start spewing massive amounts of warnings. --- python-packages/contract_wrappers/setup.py | 1 - python-packages/contract_wrappers/src/conf.py | 1 - python-packages/json_schemas/setup.py | 1 - python-packages/json_schemas/src/conf.py | 1 - python-packages/middlewares/setup.py | 1 - python-packages/middlewares/src/conf.py | 1 - python-packages/order_utils/setup.py | 1 - python-packages/order_utils/src/conf.py | 1 - python-packages/sra_client/setup.py | 1 - python-packages/sra_client/src/conf.py | 1 - 10 files changed, 10 deletions(-) diff --git a/python-packages/contract_wrappers/setup.py b/python-packages/contract_wrappers/setup.py index 08a6638d7d..4aa41535e5 100755 --- a/python-packages/contract_wrappers/setup.py +++ b/python-packages/contract_wrappers/setup.py @@ -226,7 +226,6 @@ setup( "pylint", "pytest", "sphinx", - "sphinx-autodoc-typehints", "tox", "twine", ] diff --git a/python-packages/contract_wrappers/src/conf.py b/python-packages/contract_wrappers/src/conf.py index a041a9ffe4..f353138f52 100644 --- a/python-packages/contract_wrappers/src/conf.py +++ b/python-packages/contract_wrappers/src/conf.py @@ -23,7 +23,6 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"] diff --git a/python-packages/json_schemas/setup.py b/python-packages/json_schemas/setup.py index edf013a1bc..2174f5389c 100755 --- a/python-packages/json_schemas/setup.py +++ b/python-packages/json_schemas/setup.py @@ -179,7 +179,6 @@ setup( "pylint", "pytest", "sphinx", - "sphinx-autodoc-typehints", "tox", "twine", ] diff --git a/python-packages/json_schemas/src/conf.py b/python-packages/json_schemas/src/conf.py index e8dbddacc4..1ae1493e36 100644 --- a/python-packages/json_schemas/src/conf.py +++ b/python-packages/json_schemas/src/conf.py @@ -22,7 +22,6 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"] diff --git a/python-packages/middlewares/setup.py b/python-packages/middlewares/setup.py index e9b32f2194..5257baad69 100755 --- a/python-packages/middlewares/setup.py +++ b/python-packages/middlewares/setup.py @@ -180,7 +180,6 @@ setup( "pylint", "pytest", "sphinx", - "sphinx-autodoc-typehints", "tox", "twine", ] diff --git a/python-packages/middlewares/src/conf.py b/python-packages/middlewares/src/conf.py index 4bb5a2f9f1..880a6afbc8 100644 --- a/python-packages/middlewares/src/conf.py +++ b/python-packages/middlewares/src/conf.py @@ -22,7 +22,6 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"] diff --git a/python-packages/order_utils/setup.py b/python-packages/order_utils/setup.py index 8a899270ca..16b9162328 100755 --- a/python-packages/order_utils/setup.py +++ b/python-packages/order_utils/setup.py @@ -200,7 +200,6 @@ 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 d8f56b29e6..6b6776d014 100644 --- a/python-packages/order_utils/src/conf.py +++ b/python-packages/order_utils/src/conf.py @@ -22,7 +22,6 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"] diff --git a/python-packages/sra_client/setup.py b/python-packages/sra_client/setup.py index 445b382365..36b63eb074 100755 --- a/python-packages/sra_client/setup.py +++ b/python-packages/sra_client/setup.py @@ -227,7 +227,6 @@ setup( "pylint", "pytest", "sphinx", - "sphinx-autodoc-typehints", ] }, command_options={ diff --git a/python-packages/sra_client/src/conf.py b/python-packages/sra_client/src/conf.py index 3b6477c5de..deedfcf996 100644 --- a/python-packages/sra_client/src/conf.py +++ b/python-packages/sra_client/src/conf.py @@ -22,7 +22,6 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"]