Add a User Guide (#245)

This PR introduces a new `User Guide` top level section in the
documentation explaining how to use the library in a more practical and
cohesive way than just reading through the API documentation.

The bulk of the documentation is still hosted in the code itself, as
docstrings, so users can still access most of user guide content
directly from their IDE.

It also improves the README and the docs home page, adding a quick start
section to both.

Fixes #177.

Author: llucax

README.md

@@ -28,6 +28,11 @@ channels](https://tour.golang.org/concurrency/2) but it also borrows ideas from
 
 <!-- supported-platforms -->
 
+!!! Note inline end
+
+    Newer Python versions and other operating systems and architectures might
+    work too, but they are not automatically tested, so we cannot guarantee it.
+
 The following platforms are officially supported (tested):
 
 - **Python:** 3.11
@@ -38,30 +43,214 @@ The following platforms are officially supported (tested):
 
 ## Quick Start
 
-We assume you are on a system with Python available. If that is not the case,
-please [download and install Python](https://www.python.org/downloads/) first.
+### Installing
 
-To install Frequenz Channels, you probably want to create a new virtual
-environment first. For example, if you use a `sh` compatible shell, you can do
-this:
+<!-- quick-start-installing -->
 
-```sh
-python3 -m venv .venv
-. .venv/bin/activate
-```
+!!! Tip inline end
+
+    For more details please read the [Installation
+    Guide](docs/user-guide/installation.md).
 
-Then, just install using `pip`:
+Assuming a [supported](#supported-platforms) working Python environment:
 
 ```sh
 python3 -m pip install frequenz-channels
 ```
 
+<!-- /quick-start-installing -->
+
+### Examples
+
+#### Hello World
+
+<!-- quick-start-hello-world -->
+
+```python
+import asyncio
+
+from frequenz.channels import Anycast
+
+
+async def main() -> None:
+    hello_channel = Anycast[str](name="hello-world-channel")
+    sender = hello_channel.new_sender()
+    receiver = hello_channel.new_receiver()
+
+    await sender.send("Hello World!")
+    msg = await receiver.receive()
+    print(msg)
+
+
+asyncio.run(main())
+```
+
+<!-- /quick-start-hello-world -->
+
+#### Showcase
+
+<!-- quick-start-showcase -->
+
+This is a comprehensive example that shows most of the main features of the
+library:
+
+```python
+import asyncio
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import Enum, auto
+from typing import assert_never
+
+from frequenz.channels import (
+    Anycast,
+    Broadcast,
+    Receiver,
+    Sender,
+    merge,
+    select,
+    selected_from,
+)
+from frequenz.channels.timer import Timer
+
+
+class Command(Enum):
+    PING = auto()
+    STOP_SENDER = auto()
+
+
+class ReplyCommand(Enum):
+    PONG = auto()
+
+
+@dataclass(frozen=True)
+class Reply:
+    reply: ReplyCommand
+    source: str
+
+
+async def send(
+    sender: Sender[str],
+    control_command: Receiver[Command],
+    control_reply: Sender[Reply],
+) -> None:
+    """Send a counter value every second, until a stop command is received."""
+    print(f"{sender}: Starting")
+    timer = Timer.periodic(timedelta(seconds=1.0))
+    counter = 0
+    async for selected in select(timer, control_command):
+        if selected_from(selected, timer):
+            print(f"{sender}: Sending {counter}")
+            await sender.send(f"{sender}: {counter}")
+            counter += 1
+        elif selected_from(selected, control_command):
+            print(f"{sender}: Received command: {selected.value.name}")
+            match selected.value:
+                case Command.STOP_SENDER:
+                    print(f"{sender}: Stopping")
+                    break
+                case Command.PING:
+                    print(f"{sender}: Ping received, reply with pong")
+                    await control_reply.send(Reply(ReplyCommand.PONG, str(sender)))
+                case _ as unknown:
+                    assert_never(unknown)
+    print(f"{sender}: Finished")
+
+
+async def receive(
+    receivers: list[Receiver[str]],
+    control_command: Receiver[Command],
+    control_reply: Sender[Reply],
+) -> None:
+    """Receive data from multiple channels, until no more data is received for 2 seconds."""
+    print("receive: Starting")
+    timer = Timer.timeout(timedelta(seconds=2.0))
+    print(f"{timer=}")
+    merged = merge(*receivers)
+    async for selected in select(merged, timer, control_command):
+        if selected_from(selected, merged):
+            message = selected.value
+            print(f"receive: Received {message=}")
+            timer.reset()
+            print(f"{timer=}")
+        elif selected_from(selected, control_command):
+            print(f"receive: received command: {selected.value.name}")
+            match selected.value:
+                case Command.PING:
+                    print("receive: Ping received, reply with pong")
+                    await control_reply.send(Reply(ReplyCommand.PONG, "receive"))
+                case Command.STOP_SENDER:
+                    pass  # Ignore
+                case _ as unknown:
+                    assert_never(unknown)
+        elif selected_from(selected, timer):
+            drift = selected.value
+            print(
+                f"receive: No data received for {timer.interval + drift} seconds, "
+                "giving up"
+            )
+            break
+    print("receive: Finished")
+
+
+async def main() -> None:
+    data_channel_1 = Anycast[str](name="data-channel-1")
+    data_channel_2 = Anycast[str](name="data-channel-2")
+    command_channel = Broadcast[Command](name="control-channel")  # (1)!
+    reply_channel = Anycast[Reply](name="reply-channel")
+
+    async with asyncio.TaskGroup() as tasks:
+        tasks.create_task(
+            send(
+                data_channel_1.new_sender(),
+                command_channel.new_receiver(),
+                reply_channel.new_sender(),
+            ),
+            name="send-channel-1",
+        )
+        tasks.create_task(
+            send(
+                data_channel_2.new_sender(),
+                command_channel.new_receiver(),
+                reply_channel.new_sender(),
+            ),
+            name="send-channel-2",
+        )
+        tasks.create_task(
+            receive(
+                [data_channel_1.new_receiver(), data_channel_2.new_receiver()],
+                command_channel.new_receiver(),
+                reply_channel.new_sender(),
+            ),
+            name="receive",
+        )
+
+        control_sender = command_channel.new_sender()
+        reply_receiver = reply_channel.new_receiver()
+
+        # Send a ping command to all tasks and wait for the replies
+        await control_sender.send(Command.PING)
+        print(f"main: {await reply_receiver.receive()}")
+        print(f"main: {await reply_receiver.receive()}")
+        print(f"main: {await reply_receiver.receive()}")
+
+        await asyncio.sleep(5.0)
+
+        # Stop senders, after 2 seconds not receiving any data,
+        # the receiver will stop too
+        await control_sender.send(Command.STOP_SENDER)
+
+
+asyncio.run(main())
+```
+
+<!-- /quick-start-showcase -->
+
 ## Documentation
 
-For more information, please visit the [documentation
+For more information, please read the [documentation
 website](https://frequenz-floss.github.io/frequenz-channels-python/).
 
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please
-check out the [Contributing Guide](CONTRIBUTING.md).
+check out the [Contributing Guide](docs/CONTRIBUTING.md).

RELEASE_NOTES.md

@@ -101,6 +101,8 @@
 
  ## New Features
 
+* A new User's Guide was added to the documentation and the documentation was greately improved in general.
+
 * A new `merge()` function was added to replace `Merge`.
 
 * `Anycast`

docs/SUMMARY.md

@@ -1,3 +1,4 @@
 * [Home](index.md)
+* [User Guide](user-guide/)
 * [API Reference](reference/)
 * [Contributing](CONTRIBUTING.md)

docs/index.md

@@ -16,66 +16,32 @@
    end="<!-- /supported-platforms -->"
 %}
 
-## Installation
+## Quick Start
 
-First, you need to make sure you have Python installed (at least version 3.11):
+### Installing
 
-```console
-$ python3 --version
-Python 3.11.4
-```
-
-!!! note
-
-    These instructions assume you are using a [POSIX compatible
-    `sh`](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html)
-    shell.
-
-If that command doesn't print a version newer than 3.11.0, you'll need to
-[download and install Python](https://www.python.org/downloads/) first.
-
-To install Frequenz Channels, you probably want to create a new virtual
-environment first:
-
-```sh
-mkdir my-channels-project
-cd my-channels-project
-python3 -m venv .venv
-. .venv/bin/activate
-```
-
-!!! tip
-
-    Using [`direnv`](https://direnv.net/) can greatly simplify this process as
-    it automates the creation, activation, and deactivation of the virtual
-    environment. The first time you enable `direnv`, the virtual environment
-    will be created, and each time you enter or leave a subdirectory, it will be
-    activated and deactivated, respectively.
-
-    ```sh
-    sudo apt install direnv # if you use Debian/Ubuntu
-    mkdir my-channels-project
-    cd my-channels-project
-    echo "layout python python3" > .envrc
-    direnv allow
-    ```
+{%
+   include-markdown "../README.md"
+   start="<!-- quick-start-installing -->"
+   end="<!-- /quick-start-installing -->"
+%}
 
-    This will create the virtual environment and activate it automatically for you.
+### Examples
 
-Now you can install Frequenz Channels by using `pip` (if you don't have `pip` installed
-you can follow [the official instructions](https://pip.pypa.io/en/stable/installation/)):
+!!! Example "Hello World"
 
-```sh
-python3 -m pip install frequenz-channels
-```
+    {%
+        include-markdown "../README.md"
+        preserve-includer-indent=true
+        start="<!-- quick-start-hello-world -->"
+        end="<!-- /quick-start-hello-world -->"
+    %}
 
-To verify that the installation worked, you can invoke the Python interpreter and
-import the `frequenz.channels` module:
+!!! Example "Showcase"
 
-```console
-$ python3
-Python 3.11.4 (main, Jun  7 2023, 10:13:09) [GCC 12.2.0] on linux
-Type "help", "copyright", "credits" or "license" for more information.
->>> import frequenz.channels
->>>
-```
+    {%
+        include-markdown "../README.md"
+        preserve-includer-indent=true
+        start="<!-- quick-start-showcase -->"
+        end="<!-- /quick-start-showcase -->"
+    %}

docs/user-guide/SUMMARY.md

@@ -0,0 +1,7 @@
+* [Quick Start](quick-start.md)
+* [Installation](installation.md)
+* [Channels](channels/)
+* [Sending](sending.md)
+* [Receiving](receiving/)
+* [Error Handling](error-handling.md)
+* [Utilities](utilities/)

docs/user-guide/channels/anycast.md

@@ -0,0 +1,10 @@
+# Anycast
+
+::: frequenz.channels._anycast.Anycast
+    options:
+        inherited_members: []
+        members: []
+        show_bases: false
+        show_root_heading: false
+        show_root_toc_entry: false
+        show_source: false

docs/user-guide/channels/broadcast.md

@@ -0,0 +1,10 @@
+# Broadcast
+
+::: frequenz.channels._broadcast.Broadcast
+    options:
+        inherited_members: []
+        members: []
+        show_bases: false
+        show_root_heading: false
+        show_root_toc_entry: false
+        show_source: false