doc/messaging: extend introduction.

Also drop separate, nearly empty Mailboxes page. Ultimately we may separate this page into two pieces again, but for now a single concise page is clearer than two incomplete pages.

doc/api/index.rst

@@ -39,5 +39,4 @@ Intro
 
    signaltypes
    motors
-   mailboxes
 ..    frames

doc/api/messaging.rst

@@ -1,12 +1,28 @@
 :mod:`messaging <pybricks.messaging>` -- Messaging
 ==================================================
 
-.. automodule:: pybricks.messaging
-    :no-members:
+.. module:: pybricks.messaging
 
 .. currentmodule:: pybricks.messaging
 
-Introductory text. An example network is shown in :numref:`fig_messaging`.
+An EV3 Brick can send information to another EV3 Brick using Bluetooth. This
+page shows you how to connect multiple bricks and how to write scripts to send
+messages between them.
+
+Pairing EV3 Bricks
+------------------
+
+.. todo::
+
+    Brief intro and screenshots of pairing with brickman.
+
+Server and Client
+-----------------
+
+A wireless network consists of EV3 Bricks acting as servers or clients. A
+example with one server and one client is shown in :numref:`fig_messaging`.
+Messages can be sent in both ways: the server can send a message to the client,
+and the client can send a message to the server.
 
 .. _fig_messaging:
 
@@ -17,9 +33,35 @@ Introductory text. An example network is shown in :numref:`fig_messaging`.
 
    An example network with one server and one clients.
 
+.. toggle-header::
+    :header: **Show/hide full server example**
+
+    **Example: EV3 Bluetooth Server.**
+
+    This is the full version of the excerpt shown in :numref:`fig_messaging`.
+
+    .. literalinclude:: ../../pybricks-projects/snippets/ev3/bluetooth_server/server.py
 
-Connections
-------------
+.. toggle-header::
+    :header: **Show/hide full client example**
+
+    **Example: EV3 Bluetooth Client.**
+
+    This is the full version of the excerpt shown in :numref:`fig_messaging`.
+
+    .. literalinclude:: ../../pybricks-projects/snippets/ev3/bluetooth_client/client.py
+
+
+The only difference between the client and the server is which one initiates
+the connection at the beginning of the program:
+
+    - The **server** must always be started first. It uses the
+      ``BluetoothMailboxServer`` class. Then it waits for clients using
+      the ``wait_for_connection`` method.
+    - The **client** uses the ``BluetoothMailboxClient`` class. It
+      connects to the server using the ``connect`` method.
+    - After that, sending and receiving messages is done in the same way on
+      both EV3 Bricks.
 
 .. autoclass:: BluetoothMailboxServer
 
@@ -29,7 +71,15 @@ Connections
 Mailboxes
 ---------
 
-Mailboxes are used to send data to and from other EV3s.
+Mailboxes are used to send data to and from other EV3 Bricks.
+
+A Mailbox has a ``name``, similar to the "subject" of an email. If two EV3
+Bricks have a Mailbox with the same name, they can send messages between them.
+Each EV3 Brick can read its own Mailbox, and send messages to the Mailbox on
+the other EV3 Brick.
+
+Depending on the type of messages you would like to exchange (bytes, booleans,
+numbers, or text), you can choose one of the Mailboxes below.
 
 .. autoclass:: Mailbox
 
@@ -42,8 +92,12 @@ Mailboxes are used to send data to and from other EV3s.
 .. autoclass:: TextMailbox
     :no-members:
 
-Bigger networks
-----------------
+Making bigger networks
+----------------------
+
+The classes in this module are not limited to just two EV3 Bricks. for
+example, you can add more clients to your network. An example with pseudo-code
+is shown in :numref:`fig_messaging_network`.
 
 .. _fig_messaging_network: