chore(do not merge): Experiment on docc

.github/workflows/gh-pages.yaml

@@ -43,6 +43,8 @@ jobs:
         run: |
           tox -e spec-docs
           touch .tox/docs/.nojekyll
+        env:
+          DOCC_SKIP_DIFFS: ${{ (github.event_name != 'push' || github.ref_name != github.event.repository.default_branch) && '1' || '' }}
 
       - name: Upload Pages Artifact
         id: artifact

.gitignore

@@ -89,3 +89,6 @@ logs/
 env.yaml
 
 site/
+
+# Vendored static assets (overrides dist/ rule)
+!vendor/docc/docc/plugins/html/static/**/dist/

pyproject.toml

@@ -364,6 +364,7 @@ ignore_names = ["pytest_*"]
 
 [tool.ruff]
 line-length = 79
+exclude = ["vendor"]
 
 [tool.ruff.lint]
 exclude = ["tests/fixtures"]
@@ -458,6 +459,7 @@ skip = [
     "tmp",
     "*.coverage*",
     "uv.lock",
+    "vendor",
 ]
 ignore-words = "whitelist.txt"  # Custom whitelist file
 count = true                    # Display counts of errors
@@ -496,7 +498,8 @@ required-version = ">=0.7.0"
 extra-build-dependencies = { ethash = ["setuptools", "cmake>=4.2.1,<5"] }
 
 [tool.uv.workspace]
-members = ["packages/*"]
+members = ["packages/*", "vendor/*"]
 
 [tool.uv.sources]
 ethereum-execution-testing = { workspace = true }
+docc = { workspace = true }

src/ethereum_spec_tools/docc.py

@@ -19,6 +19,7 @@
 
 import dataclasses
 import logging
+import os
 from collections import defaultdict
 from itertools import tee, zip_longest
 from pathlib import PurePath
@@ -89,6 +90,10 @@ def discover(self, known: FrozenSet[T]) -> Iterator[Source]:
         """
         Find sources.
         """
+        if os.environ.get("DOCC_SKIP_DIFFS"):
+            logging.info("Skipping diff discovery (DOCC_SKIP_DIFFS)")
+            return
+
         forks = {f.path: f for f in self.forks if f.path is not None}
 
         by_fork: Dict[Hardfork, Dict[PurePath, Source]] = defaultdict(dict)

tox.ini

@@ -194,6 +194,7 @@ commands =
 [testenv:spec-docs]
 description = Generate documentation for the specification code using docc
 basepython = python3
+passenv = DOCC_SKIP_DIFFS
 commands =
     docc --output "{toxworkdir}/docs"
     python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs" / "index.html"))'

vendor/docc/docc/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (C) 2022-2024 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+The documentation compiler.
+"""
+
+__version__ = "0.3.1"
+"Current version of docc"

vendor/docc/docc/__main__.py

@@ -0,0 +1,22 @@
+# Copyright (C) 2022-2023 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Forwards to `docc.cli` when the module is executed directly.
+"""
+
+from docc.cli import main
+
+main()

vendor/docc/docc/build.py

@@ -0,0 +1,74 @@
+# Copyright (C) 2022-2024 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Implementations of `Builder` convert each `Source` into a `Document`.
+"""
+
+from abc import ABC, abstractmethod
+from contextlib import AbstractContextManager
+from types import TracebackType
+from typing import Dict, Iterator, Optional, Set, Tuple, Type
+
+from .document import Document
+from .plugins.loader import Loader
+from .settings import PluginSettings, Settings
+from .source import Source
+
+
+class Builder(AbstractContextManager["Builder", None], ABC):
+    """
+    Consumes unprocessed `Source` instances and creates `Document`s.
+    """
+
+    @abstractmethod
+    def __init__(self, config: PluginSettings) -> None:
+        """
+        Create a Builder with the given configuration.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build(
+        self,
+        unprocessed: Set[Source],
+        processed: Dict[Source, Document],
+    ) -> None:
+        """
+        Consume unprocessed Sources and insert their Documents into processed.
+        """
+        raise NotImplementedError()
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        """
+        Context handler clean-up function.
+        """
+
+
+def load(settings: Settings) -> Iterator[Tuple[str, Builder]]:
+    """
+    Load the builder plugins as requested in settings.
+    """
+    loader = Loader()
+
+    for name in settings.build:
+        class_ = loader.load(Builder, name)
+        plugin_settings = settings.for_plugin(name)
+        yield (name, class_(plugin_settings))