feat(doc): replace index with __init__.py (#2779)

Author: SamWilsn

pyproject.toml

@@ -225,7 +225,7 @@ actionlint = [
     "shellcheck-py>=0.10",
 ]
 doc = [
-    "docc>=0.5.1,<0.6.0",
+    "docc>=0.6.0,<0.7.0",
     "fladrif>=0.2.0,<0.3.0",
     "mistletoe>=1.5.0,<2",
 ]
@@ -273,6 +273,7 @@ whitelist = "ethereum_spec_tools.whitelist:main"
 [project.entry-points."docc.plugins"]
 "ethereum_spec_tools.docc.listing" = "ethereum_spec_tools.docc:EthereumListingDiscover"
 "ethereum_spec_tools.docc.discover" = "ethereum_spec_tools.docc:EthereumDiscover"
+"ethereum_spec_tools.docc.python" = "ethereum_spec_tools.docc:EthereumPythonDiscover"
 "ethereum_spec_tools.docc.build" = "ethereum_spec_tools.docc:EthereumBuilder"
 "ethereum_spec_tools.docc.fix-indexes" = "ethereum_spec_tools.docc:FixIndexTransform"
 "ethereum_spec_tools.docc.minimize-diffs" = "ethereum_spec_tools.docc:MinimizeDiffsTransform"
@@ -311,7 +312,7 @@ context = [
 discovery = [
     "docc.search.discover",
     "docc.html.discover",
-    "docc.python.discover",
+    "ethereum_spec_tools.docc.python",
     "ethereum_spec_tools.docc.discover",
     "ethereum_spec_tools.docc.listing",
     "docc.files.discover",
@@ -341,7 +342,7 @@ excluded_references = [
     "ethereum_spec_tools.lint.lints",   # This is a namespace package.
 ]
 
-[tool.docc.plugins."docc.python.discover"]
+[tool.docc.plugins."ethereum_spec_tools.docc.python"]
 paths = [
     "src",
 ]

src/ethereum_spec_tools/docc.py

@@ -21,6 +21,7 @@
 import logging
 import os
 from collections import defaultdict
+from functools import total_ordering
 from itertools import tee, zip_longest
 from pathlib import PurePath
 from typing import (
@@ -51,7 +52,8 @@
     ListingNode,
     ListingSource,
 )
-from docc.plugins.python import PythonBuilder
+from docc.plugins.python import PythonBuilder, PythonDiscover
+from docc.plugins.python.cst import PythonSource
 from docc.plugins.references import Definition, Reference
 from docc.settings import PluginSettings
 from docc.source import Source
@@ -76,24 +78,65 @@ def pairwise(iterable: Iterable[G]) -> Iterable[Tuple[G, G]]:
     return zip(a, b, strict=False)
 
 
+@total_ordering
+@dataclasses.dataclass(frozen=True)
+class _EthereumSortKey:
+    sort: int
+    path: PurePath
+
+    def __lt__(self, other: object) -> bool:
+        if isinstance(other, _EthereumSortKey):
+            return (self.sort, self.path) < (other.sort, other.path)
+        elif isinstance(other, PurePath):
+            return self.path < other
+        return NotImplemented
+
+
+class _EthereumPythonSource(PythonSource):
+    _sort: Final[int]
+
+    def __init__(
+        self,
+        root_path: PurePath,
+        relative_path: PurePath,
+        absolute_path: PurePath,
+        sort: int,
+    ) -> None:
+        super().__init__(root_path, relative_path, absolute_path)
+        self._sort = sort
+
+    @override
+    def listing_order_key(
+        self,
+    ) -> Tuple[bool, _EthereumSortKey, None]:
+        return (
+            self.index_dir is None,
+            _EthereumSortKey(self._sort, self.output_path),
+            None,
+        )
+
+
 class _EthereumListingSource(ListingSource):
     _sort: Final[int]
 
     def __init__(
         self,
         relative_path: PurePath,
         output_path: PurePath,
-        sources: Set[Source],
         sort: int,
     ) -> None:
-        super().__init__(relative_path, output_path, sources)
+        super().__init__(relative_path, output_path)
         self._sort = sort
 
     @override
     def listing_order_key(
         self,
-    ) -> Tuple[bool, Tuple[int, PurePath], None]:
-        return (self.is_leaf, (self._sort, self.output_path), None)
+    ) -> Tuple[bool, _EthereumSortKey, None]:
+        return (
+            self.index_dir is None,
+            _EthereumSortKey(self._sort, self.output_path),
+            None,
+        )
 
 
 def _find_forks(config: PluginSettings) -> List[Hardfork]:
@@ -105,47 +148,85 @@ def _diff_path(before: Hardfork, after: Hardfork) -> PurePath:
     return PurePath("diffs") / before.short_name / after.short_name
 
 
-class EthereumListingDiscover(ListingDiscover):
-    """
-    Changes the sort order of directory listings so they render in hard fork
-    chronological order.
-    """
-
-    fork_order: List[PurePath]
-    diff_order: List[PurePath]
+class _ForkOrder:
+    forks: List[PurePath]
+    diffs: List[PurePath]
 
     def __init__(self, config: PluginSettings) -> None:
-        super().__init__(config)
         forks = _find_forks(config)
-        self.fork_order = [
+        self.forks = [
             config.unresolve_path(PurePath(f.path))
             for f in forks
             if f.path is not None
         ]
-        self.diff_order = [_diff_path(b, a).parent for b, a in pairwise(forks)]
+        self.diffs = [_diff_path(b, a).parent for b, a in pairwise(forks)]
 
-    def _fork_index(self, parent: PurePath) -> Optional[int]:
-        for idx, fork in enumerate(self.fork_order):
+    def index(self, parent: PurePath) -> Optional[int]:
+        for idx, fork in enumerate(self.forks):
             if parent.is_relative_to(fork):
                 return idx
 
-        for idx, diff in enumerate(self.diff_order):
+        for idx, diff in enumerate(self.diffs):
             if parent.is_relative_to(diff):
                 return idx
 
         return None
 
+
+class EthereumListingDiscover(ListingDiscover):
+    """
+    Changes the sort order of directory listings so they render in hard fork
+    chronological order.
+    """
+
+    _fork_order: _ForkOrder
+
+    def __init__(self, config: PluginSettings) -> None:
+        super().__init__(config)
+        self._fork_order = _ForkOrder(config)
+
     @override
     def _listing_source(
         self, source: Source, parent: PurePath
     ) -> ListingSource:
-        index = self._fork_index(parent)
+        index = self._fork_order.index(parent)
         if index is None:
             return super()._listing_source(source, parent)
         return _EthereumListingSource(
             parent,
             parent / "index",
-            set(),
+            -index,  # Reverse chronological order
+        )
+
+
+class EthereumPythonDiscover(PythonDiscover):
+    """
+    Changes the sort order of python files so they render in hard fork
+    chronological order.
+    """
+
+    _fork_order: _ForkOrder
+
+    def __init__(self, config: PluginSettings) -> None:
+        super().__init__(config)
+        self._fork_order = _ForkOrder(config)
+
+    @override
+    def _python_source(
+        self,
+        root_path: PurePath,
+        relative_path: PurePath,
+        absolute_path: PurePath,
+    ) -> PythonSource:
+        index = self._fork_order.index(relative_path)
+        if index is None:
+            return super()._python_source(
+                root_path, relative_path, absolute_path
+            )
+        return _EthereumPythonSource(
+            root_path,
+            relative_path,
+            absolute_path,
             -index,  # Reverse chronological order
         )
 
@@ -214,6 +295,9 @@ def discover(self, known: FrozenSet[T]) -> Iterator[Source]:
 
                 assert before_source or after_source
 
+                if path.name == "__init__.py":
+                    path = path.with_name("index")
+
                 output_path = _diff_path(before, after) / path
 
                 yield DiffSource(
@@ -282,6 +366,19 @@ def output_path(self) -> PurePath:
         """
         return self._output_path
 
+    @property
+    def index_dir(self) -> Optional[PurePath]:
+        """
+        For index sources, the directory the source indexes. For other sources,
+        `None`.
+
+        For example, for an output path of `./foo/index`, this should return
+        `./foo`.
+        """
+        if self.output_path.name == "index":
+            return self.output_path.parent
+        return None
+
 
 class AfterNode(Node):
     """

uv.lock

@@ -56,6 +56,7 @@
 # src/ethereum_spec_tools/docc.py
 docc.EthereumDiscover
 docc.EthereumBuilder
+docc.EthereumPythonDiscover
 docc.EthereumListingDiscover
 docc.DiffSource.show_in_listing
 docc.FixIndexTransform