Merge pull request #219 from scrapy-plugins/custom-attrs-docs

Add docs for CustomAttributes.

Author: wRAR

docs/usage/scrapy-poet.rst

@@ -131,6 +131,46 @@ resulting page object:
                 return Product(is_valid=False)
         return None
 
+.. _custom-attrs:
+
+Custom attribute extraction
+---------------------------
+
+You can request custom attribute extraction by using either a
+:class:`scrapy_zyte_api.CustomAttributes` dependency (if you need both the
+attribute values and the attribute extraction metadata) or a
+:class:`scrapy_zyte_api.CustomAttributesValues` dependency (if you only need
+the values). You need to annotate it with input data as a dictionary and, if
+needed, a dictionary with extraction options. You should use the
+:func:`scrapy_zyte_api.custom_attrs` function to create the annotation:
+
+.. code-block:: python
+
+    from typing import Annotated
+
+    from scrapy_zyte_api import CustomAttributes, custom_attrs
+
+
+    @attrs.define
+    class MyPageObject(BasePage):
+        product: Product
+        custom_attributes: Annotated[
+            CustomAttributes,
+            custom_attrs(
+                {"name": {"type": "string", "description": "name of the product"}},
+                {"method": "generate"},
+            ),
+        ]
+
+You can then access the results as the dependency value:
+
+.. code-block:: python
+
+        def parse_page(self, response: DummyResponse, page: MyPageObject):
+            ...
+            for k, v in page.custom_attributes.items():
+                ...
+
 
 Custom parameters
 =================