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/mailboxes.rst

@@ -1,79 +0,0 @@
-Mailboxes
-=========
-
-TODO: introduction... messages are sent immediately, received messages are held
-in mailbox for getting later.
-
-.. rubric:: Pairing
-
-Before two EV3s can communicate with each other via Bluetooth, they must be
-paired.
-
-TODO: screenshots of pairing with brickman, don't press the connect button!
-
-
-.. rubric:: Client and server
-
-Programs can be written using either an EV3 mailbox *client* object or an EV3
-mailbox *server* object.
-
-The only difference between the *client* and the *server* is which one
-initiates the connection at the beginning of the program. After that, sending
-and receiving messages is bidirectional and works the same from either point of
-view.
-
-The *server* waits for an incoming connection while the *client* initiates the
-connection. Therefore, the server program must always be started first. If not,
-both programs will wait forever for a connection.
-
-
-Here is a basic example where two EV3s are connected and send greetings to
-each other.
-
-.. rubric:: Client program
-
-.. literalinclude::
-    ../../pybricks-projects/snippets/ev3/bluetooth_client/client.py
-
-.. rubric:: Server program
-
-.. literalinclude::
-    ../../pybricks-projects/snippets/ev3/bluetooth_server/server.py
-
-
-.. rubric:: EV3-G compatibility
-
-TODO: screenshots of EV3-G programs, difference between client and server
-program is that client program has connect block. Server is always running.
-
-TODO: show equivalent blocks
-
-- :class:`pybricks.messaging.LogicMailbox`
-- :class:`pybricks.messaging.NumericMailbox`
-- :class:`pybricks.messaging.TextMailbox`
-
-
-.. rubric:: More than two bricks
-
-A single client EV3 can connect to multiple server EV3s or a single server EV3
-can accept connections from multiple clients.
-
-TODO: the actual implementation needs to be updated to match this example.
-
-Example::
-
-    client = EV3MailboxClient()
-
-    # connect to 4 different servers
-    client.connect(SERVER1)
-    client.connect(SERVER2)
-    client.connect(SERVER3)
-    client.connect(SERVER4)
-
-
-Example::
-
-    server = EV3MailboxServer()
-
-    # wait for 4 clients to connect
-    server.wait_for_connection(4)

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**
 
-Connections
-------------
+    **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
+
+.. 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: