Add docs for DynamicDeps.

docs/dynamic-deps.rst

@@ -0,0 +1,54 @@
+.. _dynamic-deps:
+
+====================
+Dynamic dependencies
+====================
+
+Normally the dependencies for a callback are specified statically, as type
+hints for its arguments:
+
+.. code-block:: python
+
+    import scrapy
+
+
+    class BooksSpider(scrapy.Spider):
+        ...
+
+        def start_requests(self):
+            yield scrapy.Request("http://books.toscrape.com/", self.parse_book)
+
+
+        def parse_book(self, response, book_page: BookPage, other_dep: OtherDep):
+            ...
+
+In some cases some or all of the dependencies need to be specified dynamically
+instead, e.g. because they need to be different for different pages using the
+same callback. You can use :class:`scrapy_poet.DynamicDeps
+<scrapy_poet.injection.DynamicDeps>` for this. If you add a callback argument
+with this type you can pass a list of additional dependency types in the
+request meta dictionary using the "inject" key:
+
+.. code-block:: python
+
+    import scrapy
+
+
+    class BooksSpider(scrapy.Spider):
+        ...
+
+        def start_requests(self):
+            yield scrapy.Request(
+                "http://books.toscrape.com/",
+                self.parse_book,
+                meta={"inject": [OtherDep]},
+            )
+
+
+        def parse_book(self, response, book_page: BookPage, dynamic: DynamicDeps):
+            other_dep = dynamic[OtherDep]
+            ...
+
+The types passed this way will be used in the dependency resolution as usual,
+and the created instances will be available in the
+:class:`scrapy_poet.DynamicDeps <scrapy_poet.injection.DynamicDeps>` instance.

docs/index.rst

@@ -44,6 +44,7 @@ To get started, see :ref:`intro-install` and :ref:`intro-tutorial`.
    :maxdepth: 1
 
    rules-from-web-poet
+   dynamic-deps
    stats
    providers
    testing

scrapy_poet/injection.py

@@ -56,6 +56,12 @@ class _UNDEFINED:
 
 
 class DynamicDeps(UserDict):
+    """A container for dynamic dependencies provided via the ``"inject"`` request meta key.
+
+    The dynamic dependency instances are available at the run time as dict
+    values with keys being dependency types.
+    """
+
     pass