From d1a6e3e6be2b82848146a0f6f0b7516b0748392c Mon Sep 17 00:00:00 2001
From: Sam Wilson <sam@binarycake.ca>
Date: Sun, 12 Apr 2026 15:12:48 -0400
Subject: [PATCH] feat(doc): add directory listings to py modules

---
 pyproject.toml                  |  4 +++-
 src/ethereum_spec_tools/docc.py |  9 ++++++++-
 uv.lock                         | 10 +++++-----
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 82e40bc95b0..061bf8fd466 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -225,7 +225,7 @@ actionlint = [
     "shellcheck-py>=0.10",
 ]
 doc = [
-    "docc>=0.4.0,<0.5.0",
+    "docc>=0.5.0,<0.6.0",
     "fladrif>=0.2.0,<0.3.0",
     "mistletoe>=1.5.0,<2",
 ]
@@ -302,6 +302,7 @@ omit = [
 
 [tool.docc]
 context = [
+    "docc.listing.context",
     "docc.references.context",
     "docc.search.context",
     "docc.html.context",
@@ -322,6 +323,7 @@ build = [
     "docc.resources.build",
 ]
 transform = [
+    "docc.listing.transform",
     "docc.python.transform",
     "docc.verbatim.transform",
     "docc.mistletoe.transform",
diff --git a/src/ethereum_spec_tools/docc.py b/src/ethereum_spec_tools/docc.py
index 3cf4e47b95d..9b10cd90b51 100644
--- a/src/ethereum_spec_tools/docc.py
+++ b/src/ethereum_spec_tools/docc.py
@@ -45,7 +45,7 @@
 from docc.discover import Discover, T
 from docc.document import BlankNode, Document, ListNode, Node, Visit, Visitor
 from docc.plugins import html, mistletoe, python, verbatim
-from docc.plugins.listing import Listable
+from docc.plugins.listing import Listable, ListingNode
 from docc.plugins.python import PythonBuilder
 from docc.plugins.references import Definition, Reference
 from docc.settings import PluginSettings
@@ -667,6 +667,10 @@ def shallow_equals(self, lhs: Node, rhs: Node) -> bool:
             assert isinstance(rhs, ListNode)
             return True
 
+        elif isinstance(lhs, ListingNode):
+            assert isinstance(rhs, ListingNode)
+            return True
+
         elif isinstance(lhs, verbatim.Transcribed):
             assert isinstance(rhs, verbatim.Transcribed)
             return True
@@ -750,6 +754,9 @@ def shallow_hash(self, node: Node) -> int:
         elif isinstance(node, ListNode):
             return hash(type(ListNode))
 
+        elif isinstance(node, ListingNode):
+            return hash(type(ListingNode))
+
         elif isinstance(node, verbatim.Transcribed):
             return hash(type(verbatim.Transcribed))
 
diff --git a/uv.lock b/uv.lock
index fc1bf99a549..056dedb4e0a 100644
--- a/uv.lock
+++ b/uv.lock
@@ -737,7 +737,7 @@ wheels = [
 
 [[package]]
 name = "docc"
-version = "0.4.1"
+version = "0.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "importlib-resources" },
@@ -749,9 +749,9 @@ dependencies = [
     { name = "tomli" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/5e/32/836130b1f381d7a268eeef4e980b27d73b6484ac1b8eaef418fc0acecd1c/docc-0.4.1.tar.gz", hash = "sha256:789d2c3fef02f52f485ba310e651b3390b94ea43b0b309c53513c85829348f35", size = 70249, upload-time = "2026-02-24T15:52:48.949Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a4/c0/16c29211d1681769235d1eae52646e4dd967cda77d9643935f1c30c6f0a1/docc-0.5.0.tar.gz", hash = "sha256:e49bd0fd9df6bbbd8857c9feea44dc29b3343ae8e044e8d5e0a23a4bd5c2ecb8", size = 71806, upload-time = "2026-04-15T19:01:16.554Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/eb/ad/6ea54fee2ea762b257a654827cb74ae10b515cdddb732dace59cccd406aa/docc-0.4.1-py3-none-any.whl", hash = "sha256:6dd25f72a010332f535e008b1693e41ce83da0941f79eee7c1b402c880ca3c95", size = 97150, upload-time = "2026-02-24T15:52:47.718Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/85/2c3d246676f6cb8acb4a50c4cdf130137d7f089f7ffe220ff776b4e6960e/docc-0.5.0-py3-none-any.whl", hash = "sha256:90fcf22e49ada1aaf802ead8e209bcf03316806c6799f6a2606fb927afaf7f1b", size = 98611, upload-time = "2026-04-15T19:01:15.526Z" },
 ]
 
 [[package]]
@@ -965,7 +965,7 @@ dev = [
     { name = "cairosvg", specifier = ">=2.7.0,<3" },
     { name = "codespell", specifier = "==2.4.1" },
     { name = "codespell", specifier = ">=2.4.1,<3" },
-    { name = "docc", specifier = ">=0.4.0,<0.5.0" },
+    { name = "docc", specifier = ">=0.5.0,<0.6.0" },
     { name = "ethereum-execution", extras = ["optimized"] },
     { name = "ethereum-execution-testing", editable = "packages/testing" },
     { name = "filelock", specifier = ">=3.15.1,<4" },
@@ -1003,7 +1003,7 @@ dev = [
     { name = "vulture", specifier = "==2.14.0" },
 ]
 doc = [
-    { name = "docc", specifier = ">=0.4.0,<0.5.0" },
+    { name = "docc", specifier = ">=0.5.0,<0.6.0" },
     { name = "fladrif", specifier = ">=0.2.0,<0.3.0" },
     { name = "mistletoe", specifier = ">=1.5.0,<2" },
 ]