feat(docs): added fast build mechanic with usage examples (#1202)

Co-authored-by: danceratopz <[email protected]>

Author: felix314159

docs/gen_test_case_reference.py

@@ -9,6 +9,7 @@
 import importlib
 import logging
 import sys
+from os import getenv
 
 import pytest
 from click.testing import CliRunner
@@ -24,6 +25,19 @@
 
 logger = logging.getLogger("mkdocs")
 
+
+# if docs are generated while FAST_DOCS is true, then use "tests/frontier" otherwise use "tests"
+# USAGE 1 (use fast mode):
+#       export FAST_DOCS=true && uv run mkdocs serve
+# USAGE 2 (use fast mode + hide side-effect warnings):
+#       export FAST_DOCS=true && uv run mkdocs serve 2>&1 | sed '/is not found among documentation files/d' # noqa: E501
+test_arg = "tests"
+fast_mode = getenv("FAST_DOCS")
+if fast_mode is not None:
+    if fast_mode.lower() == "true":
+        print("-" * 40, "\nWill generate docs using FAST_DOCS mode.\n" + "-" * 40)
+        test_arg = "tests/frontier"
+
 args = [
     "--override-ini",
     "filterwarnings=ignore::pytest.PytestAssertRewriteWarning",  # suppress warnings due to reload
@@ -36,10 +50,7 @@
     "-m",
     "(not blockchain_test_engine) and (not eip_version_check)",
     "-s",
-    "tests",
-    # "tests/shanghai",
-    # "tests/osaka/eip7692_eof_v1",  # noqa: SC100
-    # "tests/prague/eip2537_bls_12_381_precompiles",  # noqa: SC100
+    test_arg,
 ]
 
 runner = CliRunner()

tox.ini

@@ -42,7 +42,6 @@ commands = python -c "import src.cli.tox_helpers; src.cli.tox_helpers.markdownli
 description = Build documentation in strict mode (mkdocs)
 extras = docs
 setenv =
-    SPEC_TESTS_AUTO_GENERATE_FILES = true
     GEN_TEST_DOC_VERSION = "tox"
     # Required for `cairosvg` so tox can find `libcairo-2`.
     # https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/?h=cairo#cairo-library-was-not-found