docs: clarify pytest_deselected/pytest_collection_modifyitems usage (#12729) (#12733)

Closes #12663

(cherry picked from commit 51845fc)

Co-authored-by: Stefaan Lippens <[email protected]>

Author: patchback[bot]

changelog/12663.doc.rst

@@ -0,0 +1 @@
+Clarify that the `pytest_deselected` hook should be called from `pytest_collection_modifyitems` hook implementations when items are deselected.

src/_pytest/hookspec.py

@@ -274,6 +274,11 @@ def pytest_collection_modifyitems(
     """Called after collection has been performed. May filter or re-order
     the items in-place.
 
+    When items are deselected (filtered out from ``items``),
+    the hook :hook:`pytest_deselected` must be called explicitly
+    with the deselected items to properly notify other plugins,
+    e.g. with ``config.hook.pytest_deselected(deselected_items)``.
+
     :param session: The pytest session object.
     :param config: The pytest config object.
     :param items: List of item objects.
@@ -454,6 +459,12 @@ def pytest_collectreport(report: CollectReport) -> None:
 def pytest_deselected(items: Sequence[Item]) -> None:
     """Called for deselected test items, e.g. by keyword.
 
+    Note that this hook has two integration aspects for plugins:
+
+    - it can be *implemented* to be notified of deselected items
+    - it must be *called* from :hook:`pytest_collection_modifyitems`
+      implementations when items are deselected (to properly notify other plugins).
+
     May be called multiple times.
 
     :param items: