Add the user guide structure

These are mainly pages including docstrings from the source code. There
are only a few pages with content of their own, and they are usually
just glue to put some related docstrings together. There is one notable
exception, the general channel concepts, that don't have a better home.

The content of the docstring will be improved later to make the user
guide more cohesive.

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

Author: llucax

docs/user-guide/SUMMARY.md

@@ -1,2 +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

docs/user-guide/channels/index.md

@@ -0,0 +1,41 @@
+# Channels
+
+A channel is a communication mechanism that allows data (messages) to be
+transmitted between different coroutines. It consists of
+[senders](../sending.md), which send messages, and
+[receivers](../receiving/index.md), which receive those messages. The channel itself
+acts as a conduit for these messages.
+
+Conceptually, a channel looks like this:
+
+<center>
+```bob
+.---------.  Message    .----------.  Message    .-----------.
+| Sender  +------------>| Channel  +------------>| Receiver  |
+'---------'             '----------'             '-----------'
+```
+</center>
+
+Besides this simple model, there are many variations of channels depending on
+various factors:
+
+* How many senders and receivers can a channel have?
+
+* Do all receivers receive all messages from all senders?
+
+* How many messages can a channel hold (buffered), or can it hold any messages
+  at all (unbuffered)?
+
+* What happens if a sender tries to send a message to a full channel?
+
+    * Does the send operation block until the channel has space again?
+    * Does it fail?
+    * Does it silently drop the message?
+
+Because these questions can have many answers, there are different types of
+channels. Frequenz Channels offers a few of them:
+
+* [Anycast](anycast.md)
+* [Broadcast](broadcast.md)
+
+More might be added in the future, and you can also create your own.

docs/user-guide/error-handling.md

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

docs/user-guide/receiving/index.md

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

docs/user-guide/receiving/multiple-sources/index.md

@@ -0,0 +1,25 @@
+# Multiple Sources
+
+If you need to receive values from multiple sources it can be complicated, as
+you probably want to get the first message of each receiver as soon as it is
+available. A naive approach like this will not work:
+
+```python
+receiver1: Receiver[int] = channel1.new_receiver()
+receiver2: Receiver[int] = channel2.new_receiver()
+
+msg = await receiver1.receive()
+print(f"Received from channel1: {msg}")
+
+msg = await receiver2.receive()
+print(f"Received from channel2: {msg}")
+```
+
+The problem is that if the first message is not available in `channel1` but in
+`channel2`, the program will be blocked until a message is available in
+`channel1`, but you probably want to receive the first message from `channel2`
+as soon as it is available.
+
+Frequenz Channels provides two tools to solve this issue:
+[`merge()`][frequenz.channels.merge] and
+[`select()`][frequenz.channels.select].

docs/user-guide/receiving/multiple-sources/merge.md

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

docs/user-guide/receiving/multiple-sources/select.md

@@ -0,0 +1,11 @@
+# Selecting
+
+::: frequenz.channels._select
+    options:
+        inherited_members: []
+        members: []
+        show_bases: false
+        show_root_heading: false
+        show_root_toc_entry: false
+        show_source: false
+

docs/user-guide/sending.md

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