docs: Indent examples

This is needed to get them properly rendered and in a collapsable way.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/channels/anycast.py

@@ -24,35 +24,38 @@ class Anycast(Generic[T]):
     Uses an [deque][collections.deque] internally, so Anycast channels are not
     thread-safe.
 
+    When there are multiple channel receivers, they can be awaited
+    simultaneously using [Select][frequenz.channels.Select],
+    [Merge][frequenz.channels.Merge] or
+    [MergeNamed][frequenz.channels.MergeNamed].
+
     Example:
-    ``` python
-    async def send(sender: channel.Sender) -> None:
-        while True:
-            next = random.randint(3, 17)
-            print(f"sending: {next}")
-            await sender.send(next)
+        ``` python
+        async def send(sender: channel.Sender) -> None:
+            while True:
+                next = random.randint(3, 17)
+                print(f"sending: {next}")
+                await sender.send(next)
 
 
-    async def recv(id: int, receiver: channel.Receiver) -> None:
-        while True:
-            next = await receiver.receive()
-            print(f"receiver_{id} received {next}")
-            await asyncio.sleep(0.1) # sleep (or work) with the data
+        async def recv(id: int, receiver: channel.Receiver) -> None:
+            while True:
+                next = await receiver.receive()
+                print(f"receiver_{id} received {next}")
+                await asyncio.sleep(0.1) # sleep (or work) with the data
 
 
-    acast = channel.Anycast()
+        acast = channel.Anycast()
 
-    sender = acast.get_sender()
-    receiver_1 = acast.get_receiver()
+        sender = acast.get_sender()
+        receiver_1 = acast.get_receiver()
 
-    asyncio.create_task(send(sender))
+        asyncio.create_task(send(sender))
 
-    await recv(1, receiver_1)
-    ```
+        await recv(1, receiver_1)
+        ```
 
-    Check the `tests` and `benchmarks` directories for more examples.  When
-    there are multiple channel receivers, they can be awaited simultaneously
-    using `channel.Select` or `channel.Merge`.
+        Check the `tests` and `benchmarks` directories for more examples.
     """
 
     def __init__(self, maxsize: int = 10) -> None:

src/frequenz/channels/broadcast.py

@@ -28,35 +28,38 @@ class Broadcast(Generic[T]):
     append/pop operations on either side of a [deque][collections.deque], which
     are thread-safe.  Because of this, `Broadcast` channels are thread-safe.
 
+    When there are multiple channel receivers, they can be awaited
+    simultaneously using [Select][frequenz.channels.Select],
+    [Merge][frequenz.channels.Merge] or
+    [MergeNamed][frequenz.channels.MergeNamed].
+
     Example:
-    ``` python
-    async def send(sender: channel.Sender) -> None:
-        while True:
-            next = random.randint(3, 17)
-            print(f"sending: {next}")
-            await sender.send(next)
+        ``` python
+        async def send(sender: channel.Sender) -> None:
+            while True:
+                next = random.randint(3, 17)
+                print(f"sending: {next}")
+                await sender.send(next)
 
 
-    async def recv(id: int, receiver: channel.Receiver) -> None:
-        while True:
-            next = await receiver.receive()
-            print(f"receiver_{id} received {next}")
-            await asyncio.sleep(0.1) # sleep (or work) with the data
+        async def recv(id: int, receiver: channel.Receiver) -> None:
+            while True:
+                next = await receiver.receive()
+                print(f"receiver_{id} received {next}")
+                await asyncio.sleep(0.1) # sleep (or work) with the data
 
 
-    bcast = channel.Broadcast()
+        bcast = channel.Broadcast()
 
-    sender = bcast.get_sender()
-    receiver_1 = bcast.get_receiver()
+        sender = bcast.get_sender()
+        receiver_1 = bcast.get_receiver()
 
-    asyncio.create_task(send(sender))
+        asyncio.create_task(send(sender))
 
-    await recv(1, receiver_1)
-    ```
+        await recv(1, receiver_1)
+        ```
 
-    Check the `tests` and `benchmarks` directories for more examples.  When
-    there are multiple channel receivers, they can be awaited simultaneously
-    using `channel.Select` or `channel.Merge`.
+        Check the `tests` and `benchmarks` directories for more examples.
     """
 
     def __init__(self, name: str, resend_latest: bool = False) -> None:

src/frequenz/channels/merge.py

@@ -13,16 +13,17 @@
 class Merge(Receiver[T]):
     """Merge messages coming from multiple channels into a single stream.
 
-    For example, if there are two channel receivers with the same type, they
-    can be awaited together, and their results merged into a single stream, by
-    using `Merge` like this:
+    Example:
+        For example, if there are two channel receivers with the same type,
+        they can be awaited together, and their results merged into a single
+        stream, by using `Merge` like this:
 
-    ```python
-    merge = Merge(receiver1, receiver2)
-    while msg := await merge.receive():
-        # do something with msg
-        pass
-    ```
+        ```python
+        merge = Merge(receiver1, receiver2)
+        while msg := await merge.receive():
+            # do something with msg
+            pass
+        ```
     """
 
     def __init__(self, *args: Receiver[T]) -> None:

src/frequenz/channels/select.py

@@ -31,30 +31,31 @@ class _Selected:
 class Select:
     """Select the next available message from a group of AsyncIterators.
 
-    For example, if there are two async iterators that you want to
-    simultaneously wait on, this can be done with:
-
-    ```python
-    select = Select(name1 = receiver1, name2 = receiver2)
-    while await select.ready():
-        if msg := select.name1:
-            if val := msg.inner:
-                # do something with `val`
-                pass
-            else:
-                # handle closure of receiver.
-                pass
-        elif msg := select.name2:
-            # do something with `msg.inner`
-            pass
-    ```
-
     If `Select` was created with more `AsyncIterator` than what are read in
     the if-chain after each call to [ready()][frequenz.channels.Select.ready],
     messages coming in the additional async iterators are dropped, and
     a warning message is logged.
 
     [Receiver][frequenz.channels.Receiver]s also function as AsyncIterator.
+
+    Example:
+        For example, if there are two async iterators that you want to
+        simultaneously wait on, this can be done with:
+
+        ```python
+        select = Select(name1 = receiver1, name2 = receiver2)
+        while await select.ready():
+            if msg := select.name1:
+                if val := msg.inner:
+                    # do something with `val`
+                    pass
+                else:
+                    # handle closure of receiver.
+                    pass
+            elif msg := select.name2:
+                # do something with `msg.inner`
+                pass
+        ```
     """
 
     def __init__(self, **kwargs: AsyncIterator[Any]) -> None:

src/frequenz/channels/utils/timer.py

@@ -13,39 +13,42 @@
 class Timer(Receiver[datetime]):
     """A timer receiver that returns the timestamp every `interval` seconds.
 
-    Primarily for use with `channel.Select` calls.
-
-    When you want something to happen with a fixed period:
-    ```python
-    timer = channel.Timer(30.0)
-    select = Select(bat_1 = receiver1, timer = timer)
-    while await select.ready():
-        if msg := select.bat_1:
-            if val := msg.inner:
-                process_data(val)
-            else:
-                logging.warn("battery channel closed")
-        elif ts := select.timer:
-            # something to do once every 30 seconds
-            pass
-    ```
-
-    When you want something to happen when nothing else has happened in a
-    certain interval:
-    ```python
-    timer = channel.Timer(30.0)
-    select = Select(bat_1 = receiver1, timer = timer)
-    while await select.ready():
-        timer.reset()
-        if msg := select.bat_1:
-            if val := msg.inner:
-                process_data(val)
-            else:
-                logging.warn("battery channel closed")
-        elif ts := select.timer:
-            # something to do if there's no battery data for 30 seconds
-            pass
-    ```
+    Primarily for use with [Select][frequenz.channels.Select].
+
+    Example:
+        When you want something to happen with a fixed period:
+
+        ```python
+        timer = channel.Timer(30.0)
+        select = Select(bat_1 = receiver1, timer = timer)
+        while await select.ready():
+            if msg := select.bat_1:
+                if val := msg.inner:
+                    process_data(val)
+                else:
+                    logging.warn("battery channel closed")
+            if ts := select.timer:
+                # something to do once every 30 seconds
+                pass
+        ```
+
+        When you want something to happen when nothing else has happened in a
+        certain interval:
+
+        ```python
+        timer = channel.Timer(30.0)
+        select = Select(bat_1 = receiver1, timer = timer)
+        while await select.ready():
+            timer.reset()
+            if msg := select.bat_1:
+                if val := msg.inner:
+                    process_data(val)
+                else:
+                    logging.warn("battery channel closed")
+            if ts := select.timer:
+                # something to do if there's no battery data for 30 seconds
+                pass
+        ```
     """
 
     def __init__(self, interval: float) -> None: