From 270901fcf69d8c4282d3de859e6117bd36481ab5 Mon Sep 17 00:00:00 2001 From: Mikko Ohtamaa Date: Tue, 23 Jan 2024 20:10:49 +0100 Subject: [PATCH] Fixing Sphinx --- docs/source/conf.py | 110 +--------------------------- docs/source/tutorials/index.rst | 3 +- eth_defi/docs/__init__.py | 1 + eth_defi/docs/monkeypatch.py | 111 +++++++++++++++++++++++++++++ eth_defi/event_reader/logresult.py | 2 +- poetry.lock | 44 ++++++------ pyproject.toml | 9 +-- 7 files changed, 141 insertions(+), 139 deletions(-) create mode 100644 eth_defi/docs/__init__.py create mode 100644 eth_defi/docs/monkeypatch.py diff --git a/docs/source/conf.py b/docs/source/conf.py index 0266cd37..ef471677 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -120,112 +120,4 @@ "custom.css", ] -# Monkey-patch autosummary template context -from sphinx.ext.autosummary.generate import AutosummaryRenderer - - -def smart_fullname(fullname): - parts = fullname.split(".") - return ".".join(parts[1:]) - - -def get_first_line(docstring: str | None) -> str: - if not docstring: - # __doc__ can be None - return "" - lines = docstring.split("\n") - return lines[0] - - -def extract_module_docstring(mod_name) -> str: - """See _templates/autosummary/base.rst""" - import sys - mod = sys.modules[mod_name] - return get_first_line(getattr(mod, "__doc__", "")) - - -def extract_object_docstring(dotted_path: str) -> str: - """See _templates/autosummary/base.rst""" - from zope.dottedname.resolve import resolve - obj = resolve(dotted_path) - return get_first_line(getattr(obj, "__doc__", "")) - - - -def partial_name(fullname): - parts = fullname.split(".") - return parts[-1] - - -def obj_path(fullname): - parts = fullname.split(".") - return ".".join(parts[0:-1]) - -# Patch autosummary internals to allow our tuned templates to access -# necessary Python functions -def fixed_init(self, app, template_dir=None): - AutosummaryRenderer.__old_init__(self, app, template_dir) - self.env.filters["smart_fullname"] = smart_fullname - self.env.filters["extract_module_docstring"] = extract_module_docstring - self.env.filters["extract_object_docstring"] = extract_object_docstring - self.env.filters["partial_name"] = partial_name - self.env.filters["obj_path"] = obj_path - - - -AutosummaryRenderer.__old_init__ = AutosummaryRenderer.__init__ -AutosummaryRenderer.__init__ = fixed_init - - -# -# Monkey patch meta generation. -# See _templates/autosummary.base.rst -# - -from sphinx.addnodes import meta -from docutils import nodes -from docutils.io import StringOutput -from sphinx.util.osutil import relative_uri - -def write_doc(self, docname: str, doctree: nodes.document) -> None: - destination = StringOutput(encoding='utf-8') - doctree.settings = self.docsettings - - self.secnumbers = self.env.toc_secnumbers.get(docname, {}) - self.fignumbers = self.env.toc_fignumbers.get(docname, {}) - self.imgpath = relative_uri(self.get_target_uri(docname), '_images') - self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') - self.current_docname = docname - self.docwriter.write(doctree, destination) - self.docwriter.assemble_parts() - body = self.docwriter.parts['fragment'] - metatags = self.docwriter.clean_meta - - ctx = self.get_doc_context(docname, body, metatags) - - # Pass the custom meta attributes in raw objects instead - # of contatenad HTML soup - class ExtractMeta(nodes.GenericNodeVisitor): - - def __init__(self, document): - super().__init__(document) - self.metas = {} - - def default_visit(self, node): - if isinstance(node, meta): - self.metas[node.attributes.get("name")] = node.rawcontent - - def default_departure(self, node): - pass - - meta_extractor = ExtractMeta(doctree) - doctree.walkabout(meta_extractor) - - ctx["metas"] = meta_extractor.metas - - self.handle_page(docname, ctx, event_arg=doctree) - -from sphinx.builders.html import StandaloneHTMLBuilder -StandaloneHTMLBuilder.write_doc = write_doc - - +from eth_defi.docs import monkeypatch \ No newline at end of file diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 2a7262f3..97d94f7b 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -39,8 +39,8 @@ Example tutorials transfer make-uniswap-swap-in-python - native-token-price chainlink-price-feed + chainlink-native-token multithread-reader verify-node-integrity live-price @@ -53,6 +53,7 @@ Example tutorials aave-v3-interest-analysis slippage-and-price-impact multi-rpc-configuration + enzyme-read-vaults `For more examples, browse tests folder on Github `__. You can also search function names in `the repository `__ diff --git a/eth_defi/docs/__init__.py b/eth_defi/docs/__init__.py new file mode 100644 index 00000000..0290d792 --- /dev/null +++ b/eth_defi/docs/__init__.py @@ -0,0 +1 @@ +"""Sphinx monkeypatches to make Sphinx more useful.""" \ No newline at end of file diff --git a/eth_defi/docs/monkeypatch.py b/eth_defi/docs/monkeypatch.py new file mode 100644 index 00000000..57700981 --- /dev/null +++ b/eth_defi/docs/monkeypatch.py @@ -0,0 +1,111 @@ +"""Trying to make Sphinx more useful.""" + + +# Monkey-patch autosummary template context +from sphinx.ext.autosummary.generate import AutosummaryRenderer + + +def smart_fullname(fullname): + parts = fullname.split(".") + return ".".join(parts[1:]) + + +def get_first_line(docstring: str | None) -> str: + if not docstring: + # __doc__ can be None + return "" + lines = docstring.split("\n") + return lines[0] + + +def extract_module_docstring(mod_name) -> str: + """See _templates/autosummary/base.rst""" + import sys + mod = sys.modules[mod_name] + return get_first_line(getattr(mod, "__doc__", "")) + + +def extract_object_docstring(dotted_path: str) -> str: + """See _templates/autosummary/base.rst""" + from zope.dottedname.resolve import resolve + obj = resolve(dotted_path) + return get_first_line(getattr(obj, "__doc__", "")) + + + +def partial_name(fullname): + parts = fullname.split(".") + return parts[-1] + + +def obj_path(fullname): + parts = fullname.split(".") + return ".".join(parts[0:-1]) + +# Patch autosummary internals to allow our tuned templates to access +# necessary Python functions +def fixed_init(self, app, template_dir=None): + AutosummaryRenderer.__old_init__(self, app, template_dir) + self.env.filters["smart_fullname"] = smart_fullname + self.env.filters["extract_module_docstring"] = extract_module_docstring + self.env.filters["extract_object_docstring"] = extract_object_docstring + self.env.filters["partial_name"] = partial_name + self.env.filters["obj_path"] = obj_path + + + +AutosummaryRenderer.__old_init__ = AutosummaryRenderer.__init__ +AutosummaryRenderer.__init__ = fixed_init + + +# +# Monkey patch meta generation. +# See _templates/autosummary.base.rst +# + +from sphinx.addnodes import meta +from docutils import nodes +from docutils.io import StringOutput +from sphinx.util.osutil import relative_uri + +def write_doc(self, docname: str, doctree: nodes.document) -> None: + destination = StringOutput(encoding='utf-8') + doctree.settings = self.docsettings + + self.secnumbers = self.env.toc_secnumbers.get(docname, {}) + self.fignumbers = self.env.toc_fignumbers.get(docname, {}) + self.imgpath = relative_uri(self.get_target_uri(docname), '_images') + self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') + self.current_docname = docname + self.docwriter.write(doctree, destination) + self.docwriter.assemble_parts() + body = self.docwriter.parts['fragment'] + metatags = self.docwriter.clean_meta + + ctx = self.get_doc_context(docname, body, metatags) + + # Pass the custom meta attributes in raw objects instead + # of contatenad HTML soup + class ExtractMeta(nodes.GenericNodeVisitor): + + def __init__(self, document): + super().__init__(document) + self.metas = {} + + def default_visit(self, node): + if isinstance(node, meta): + self.metas[node.attributes.get("name")] = node.rawcontent + + def default_departure(self, node): + pass + + meta_extractor = ExtractMeta(doctree) + doctree.walkabout(meta_extractor) + + ctx["metas"] = meta_extractor.metas + + self.handle_page(docname, ctx, event_arg=doctree) + +from sphinx.builders.html import StandaloneHTMLBuilder +StandaloneHTMLBuilder.write_doc = write_doc + diff --git a/eth_defi/event_reader/logresult.py b/eth_defi/event_reader/logresult.py index a9684611..28afedb3 100644 --- a/eth_defi/event_reader/logresult.py +++ b/eth_defi/event_reader/logresult.py @@ -32,7 +32,7 @@ class LogResult(TypedDict): Example data (PancakeSwap swap): - .. code-block:: python + .. code-block:: text { 'address': '0xc91cd2b9c9aafe494cf3ccc8bee7795deb17231a', diff --git a/poetry.lock b/poetry.lock index 47b0c083..53175702 100644 --- a/poetry.lock +++ b/poetry.lock @@ -4519,34 +4519,32 @@ test = ["pytest"] [[package]] name = "sphinxcontrib-devhelp" -version = "1.0.6" -description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp documents" +version = "1.0.2" +description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document." optional = true -python-versions = ">=3.9" +python-versions = ">=3.5" files = [ - {file = "sphinxcontrib_devhelp-1.0.6-py3-none-any.whl", hash = "sha256:6485d09629944511c893fa11355bda18b742b83a2b181f9a009f7e500595c90f"}, - {file = "sphinxcontrib_devhelp-1.0.6.tar.gz", hash = "sha256:9893fd3f90506bc4b97bdb977ceb8fbd823989f4316b28c3841ec128544372d3"}, + {file = "sphinxcontrib-devhelp-1.0.2.tar.gz", hash = "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"}, + {file = "sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e"}, ] [package.extras] lint = ["docutils-stubs", "flake8", "mypy"] -standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] name = "sphinxcontrib-htmlhelp" -version = "2.0.5" +version = "2.0.1" description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files" optional = true -python-versions = ">=3.9" +python-versions = ">=3.8" files = [ - {file = "sphinxcontrib_htmlhelp-2.0.5-py3-none-any.whl", hash = "sha256:393f04f112b4d2f53d93448d4bce35842f62b307ccdc549ec1585e950bc35e04"}, - {file = "sphinxcontrib_htmlhelp-2.0.5.tar.gz", hash = "sha256:0dc87637d5de53dd5eec3a6a01753b1ccf99494bd756aafecd74b4fa9e729015"}, + {file = "sphinxcontrib-htmlhelp-2.0.1.tar.gz", hash = "sha256:0cbdd302815330058422b98a113195c9249825d681e18f11e8b1f78a2f11efff"}, + {file = "sphinxcontrib_htmlhelp-2.0.1-py3-none-any.whl", hash = "sha256:c38cb46dccf316c79de6e5515e1770414b797162b23cd3d06e67020e1d2a6903"}, ] [package.extras] lint = ["docutils-stubs", "flake8", "mypy"] -standalone = ["Sphinx (>=5)"] test = ["html5lib", "pytest"] [[package]] @@ -4579,34 +4577,32 @@ test = ["flake8", "mypy", "pytest"] [[package]] name = "sphinxcontrib-qthelp" -version = "1.0.7" -description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp documents" +version = "1.0.3" +description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document." optional = true -python-versions = ">=3.9" +python-versions = ">=3.5" files = [ - {file = "sphinxcontrib_qthelp-1.0.7-py3-none-any.whl", hash = "sha256:e2ae3b5c492d58fcbd73281fbd27e34b8393ec34a073c792642cd8e529288182"}, - {file = "sphinxcontrib_qthelp-1.0.7.tar.gz", hash = "sha256:053dedc38823a80a7209a80860b16b722e9e0209e32fea98c90e4e6624588ed6"}, + {file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"}, + {file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"}, ] [package.extras] lint = ["docutils-stubs", "flake8", "mypy"] -standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] name = "sphinxcontrib-serializinghtml" -version = "1.1.10" -description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)" +version = "1.1.5" +description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)." optional = true -python-versions = ">=3.9" +python-versions = ">=3.5" files = [ - {file = "sphinxcontrib_serializinghtml-1.1.10-py3-none-any.whl", hash = "sha256:326369b8df80a7d2d8d7f99aa5ac577f51ea51556ed974e7716cfd4fca3f6cb7"}, - {file = "sphinxcontrib_serializinghtml-1.1.10.tar.gz", hash = "sha256:93f3f5dc458b91b192fe10c397e324f262cf163d79f3282c158e8436a2c4511f"}, + {file = "sphinxcontrib-serializinghtml-1.1.5.tar.gz", hash = "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"}, + {file = "sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl", hash = "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd"}, ] [package.extras] lint = ["docutils-stubs", "flake8", "mypy"] -standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] @@ -5259,4 +5255,4 @@ test = ["pytest-xdist"] [metadata] lock-version = "2.0" python-versions = ">=3.10,<3.13" -content-hash = "b6debe92e024c38f097d4c9aef1a955a1eb60460276382bb669f2b8e21634049" +content-hash = "0f92fb7e89d79e62cf76af87dbb4648d92979e172cbbc92267b39c4143e7f185" diff --git a/pyproject.toml b/pyproject.toml index 6eccc33c..48ccce7c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,10 +61,11 @@ nbsphinx = {version = "^0.8.9", optional = true} sphinx-rtd-theme = {version = "^1.0.0", optional = true} zope-dottedname = {version = "^6.0", optional = true} furo = {version = "^2022.6.4.1", optional = true} - -# Version pindowns -# https://github.com/sphinx-doc/sphinxcontrib-applehelp/blob/master/CHANGES -sphinxcontrib-applehelp = {version = "1.0.4", optional = true} +sphinxcontrib-applehelp = {version = "1.0.4", optional = true} # Version pindowns https://github.com/sphinx-doc/sphinxcontrib-applehelp/blob/master/CHANGES +sphinxcontrib-devhelp = {version = "1.0.2", optional = true} # Version pindowns https://github.com/sphinx-doc/sphinxcontrib-devhelp/blob/master/CHANGES +sphinxcontrib-htmlhelp = {version = "2.0.1", optional = true} # Version pindowns https://github.com/sphinx-doc/sphinxcontrib-htmlhelp/blob/master/CHANGES +sphinxcontrib-serializinghtml = {version = "1.1.5", optional = true} # Version pindowns https://github.com/sphinx-doc/sphinxcontrib-serializinghtml/blob/master/CHANGES +sphinxcontrib-qthelp = {version = "1.0.3", optional = true} # Version pindowns https://github.com/sphinx-doc/sphinxcontrib-qthelp/blob/master/CHANGES [tool.poetry.dev-dependencies] pytest = "^7.4.3"