From 661ef6900ddd7d379f4b7bce96b20d8a19f45faa Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Wed, 17 Jul 2024 14:55:18 +0200
Subject: [PATCH 1/2] Improves the documentation on `Receiver.filter`

This also adds a new section to the documentation explaining how to
filter to the user guide.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 RELEASE_NOTES.md                   | 14 +-------------
 src/frequenz/channels/_receiver.py | 24 ++++++++++++++++++++++--
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 96a0240b..2583be48 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -2,16 +2,4 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
-
-## New Features
-
-<!-- Here goes the main new features and examples or instructions on how to use them -->
-
-## Bug Fixes
-
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+This release improves the documentation on `Receiver.filter`.
diff --git a/src/frequenz/channels/_receiver.py b/src/frequenz/channels/_receiver.py
index dbb533f3..c01c8102 100644
--- a/src/frequenz/channels/_receiver.py
+++ b/src/frequenz/channels/_receiver.py
@@ -55,6 +55,25 @@
 [`map()`][frequenz.channels.Receiver.map] returns a new full receiver, so you can
 use it in any of the ways described above.
 
+# Message Filtering
+
+If you need to filter the received messages, receivers provide a
+[`filter()`][frequenz.channels.Receiver.filter] method to easily do so:
+
+```python show_lines="6:"
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+async for message in receiver.filter(lambda x: x % 2 == 0):
+    print(message)  # Only even numbers will be printed
+```
+
+As with [`map()`][frequenz.channels.Receiver.map],
+[`filter()`][frequenz.channels.Receiver.filter] returns a new full receiver, so you can
+use it in any of the ways described above.
+
 # Error Handling
 
 !!! Tip inline end
@@ -254,10 +273,11 @@ def filter(
             original receiver and use that instead.
 
         Args:
-            filter_function: The function to be applied on incoming messages.
+            filter_function: The function to be applied on incoming messages to
+                determine if they should be received.
 
         Returns:
-            A new receiver that applies the function on the received messages.
+            A new receiver that only receives messages that pass the filter.
         """
         return _Filter(receiver=self, filter_function=filter_function)
 

From 490dd520d87a9b071c3778af2ed149dc48ae76bb Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Wed, 17 Jul 2024 15:04:48 +0200
Subject: [PATCH 2/2] Fix breaking change in new version of griffe

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 docs/_scripts/macros.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/_scripts/macros.py b/docs/_scripts/macros.py
index e316cc22..85600826 100644
--- a/docs/_scripts/macros.py
+++ b/docs/_scripts/macros.py
@@ -6,8 +6,7 @@
 from typing import Any
 
 import markdown as md
-from griffe import Object
-from griffe.collections import ModulesCollection
+from griffe import ModulesCollection, Object
 from markdown.extensions import toc
 from mkdocs_macros import plugin as macros
 from mkdocstrings_handlers.python.handler import PythonHandler