test: run the writing-integrations examples in test-docs (#652)

Author: lesnik512

conftest.py

@@ -8,6 +8,7 @@
 import ast
 import asyncio
 import inspect
+import pathlib
 from collections.abc import Iterator
 
 import pytest
@@ -23,10 +24,11 @@
 _EXCLUDED_PAGES = (
     "adr/*",
     "agents/*",
-    "integrations/*",
     "migration/*",
 )
 
+_FRAMEWORK_INDEPENDENT_INTEGRATION_PAGES = frozenset({"writing-integrations.md"})
+
 _EXPECTED_ERROR_KEY = "__docs_expected_error__"
 
 _RAISES_LEXER = DirectiveInHTMLCommentLexer("raises", arguments=r"\w+")
@@ -65,7 +67,7 @@ def _evaluate_python(example: Example) -> None:
         pytest.fail(f"expected the block to raise {expected_error}, it raised nothing")
 
 
-pytest_collect_file = Sybil(
+_collect_docs = Sybil(
     parsers=[
         CodeBlockParser("python", _evaluate_python),
         SkipParser(),
@@ -76,3 +78,9 @@ def _evaluate_python(example: Example) -> None:
     patterns=["*.md"],
     excludes=_EXCLUDED_PAGES,
 ).pytest()
+
+
+def pytest_collect_file(file_path: pathlib.Path, parent: pytest.Collector) -> pytest.Collector | None:
+    if file_path.parent.name == "integrations" and file_path.name not in _FRAMEWORK_INDEPENDENT_INTEGRATION_PAGES:
+        return None
+    return _collect_docs(file_path, parent)

docs/agents/docs-style.md

@@ -62,10 +62,10 @@ not ban the English words: an example class may be a `UserService`, and an appli
 ## Code samples run
 
 `just test-docs` runs every `python` block in the site, page by page, with each page's blocks
-sharing one namespace in order. `integrations/` and `migration/` are excluded in `conftest.py`. A
-block that can't run as written gets `<!-- skip: next "reason" -->` on the line above its fence.
-Setup the reader doesn't need to see goes in an `<!-- invisible-code-block: python -->` comment. A
-block that demonstrates an error gets `<!-- raises: ErrorClassName -->` right above its fence, after
-any hidden setup, and passes only if it raises that class. An import of a third-party package that
-isn't installed here skips only if the package is listed in `conftest.py`; any other missing import
-fails.
+sharing one namespace in order. `conftest.py` excludes `migration/` and every framework page under
+`integrations/`; `writing-integrations.md` needs no framework and runs. A block that can't run as
+written gets `<!-- skip: next "reason" -->` on the line above its fence. Setup the reader doesn't
+need to see goes in an `<!-- invisible-code-block: python -->` comment. A block that demonstrates an
+error gets `<!-- raises: ErrorClassName -->` right above its fence, after any hidden setup, and
+passes only if it raises that class. An import of a third-party package that isn't installed here
+skips only if the package is listed in `conftest.py`; any other missing import fails.

docs/integrations/writing-integrations.md

@@ -31,6 +31,41 @@ child container should open at. This is the single source of the
 kind → scope mapping; `setup_di` registers them and the child-container builder
 dispatches off them.
 
+<!-- invisible-code-block: python
+import dataclasses
+import types
+import typing
+
+from modern_di import Container, Group, Scope, providers
+
+
+class _App:
+    def __init__(self) -> None:
+        self.state = types.SimpleNamespace()
+
+
+class _Request:
+    def __init__(self, app: _App) -> None:
+        self.app = app
+
+
+class _WebSocket:
+    def __init__(self, app: _App) -> None:
+        self.app = app
+
+
+myfw = types.SimpleNamespace(App=_App, Request=_Request, WebSocket=_WebSocket, Depends=lambda dependency: dependency)
+HTTPConnection = _Request
+T_co = typing.TypeVar("T_co", covariant=True)
+
+
+class MyService: ...
+
+
+class Dependencies(Group):
+    service = providers.Factory(MyService, scope=Scope.REQUEST)
+-->
+
 ```python
 from modern_di import Scope, providers
 
@@ -168,6 +203,18 @@ def FromDI(dependency: providers.AbstractProvider[T_co] | type[T_co]) -> T_co:
     return typing.cast(T_co, myfw.Depends(Dependency(integrations.Marker(dependency))))
 ```
 
+<!-- invisible-code-block: python
+app = myfw.App()
+setup_di(app, Container(groups=[Dependencies]))
+request = myfw.Request(app)
+builder = build_di_container(request)
+request_container = await anext(builder)
+assert request_container.scope is Scope.REQUEST
+assert request_container.resolve(myfw.Request) is request
+assert isinstance(await FromDI(Dependencies.service)(request_container), MyService)
+await builder.aclose()
+-->
+
 `Marker.resolve(container)` is a single call, invariant across every
 integration and both modes: it hands the wrapped provider-or-type to
 `container.resolve_dependency`, which routes to `resolve_provider`/`resolve`