docs: rewrite and restructure explanation about en-/decoding payload types

Author: empicano

CONTRIBUTING.md

@@ -82,7 +82,7 @@ The documentation uses [Sphinx](https://www.sphinx-doc.org/en/master/). The sour
 
 After running `git commit`, `pre-commit` will check the committed code. This check can be passed, skipped or failed.
 
-If the check failed, it is possible that `pre-commit` auto-fixed the code, so you only need to re-stage and re-commit. If it did not auto-fie the code, you will need to do so manually.
+If the check failed, it is possible that `pre-commit` auto-fixed the code, so you only need to re-stage and re-commit. If it did not auto-fix the code, you will need to do so manually.
 
 `pre-commit` will only check the code that is staged, the unstaged code will be stashed during the checks.
 

README.md

@@ -15,24 +15,24 @@
 
 Write code like this:
 
-**Subscriber**
+**Publisher**
 
 ```python
 async with Client("test.mosquitto.org") as client:
-    async with client.messages() as messages:
-        await client.subscribe("humidity/#")
-        async for message in messages:
-            print(message.payload)
+    await client.publish("humidity/outside", payload=0.38)
 ```
 
-**Publisher**
+**Subscriber**
 
 ```python
 async with Client("test.mosquitto.org") as client:
-    await client.publish("humidity/outside", payload=0.38)
+    async with client.messages() as messages:
+        await client.subscribe("humidity/#")
+        async for message in messages:
+            print(message.payload)
 ```
 
-_asyncio-mqtt_ combines the stability of the time-proven [paho-mqtt](https://github.com/eclipse/paho.mqtt.python) library with a modern, asyncio-based interface.
+asyncio-mqtt combines the stability of the time-proven [paho-mqtt](https://github.com/eclipse/paho.mqtt.python) library with a modern, asyncio-based interface.
 
 - No more callbacks! 👍
 - No more return codes (welcome to the `MqttError`)
@@ -41,6 +41,8 @@ _asyncio-mqtt_ combines the stability of the time-proven [paho-mqtt](https://git
 - Fully type-hinted
 - Did we mention no more callbacks?
 
+The whole thing is less than [900 lines of code](https://github.com/sbtinstruments/asyncio-mqtt/blob/main/asyncio_mqtt/client.py).
+
 <!-- pitch end -->
 
 ---
@@ -53,15 +55,15 @@ _asyncio-mqtt_ combines the stability of the time-proven [paho-mqtt](https://git
 
 ## Installation
 
-_asyncio-mqtt_ can be installed via `pip install asyncio-mqtt`. It requires Python 3.7+ to run. The only dependency is [paho-mqtt](https://github.com/eclipse/paho.mqtt.python).
+asyncio-mqtt can be installed via `pip install asyncio-mqtt`. It requires Python 3.7+ to run. The only dependency is [paho-mqtt](https://github.com/eclipse/paho.mqtt.python).
 
 If you can't wait for the latest version and want to install directly from GitHub, use:
 
 `pip install git+https://github.com/sbtinstruments/asyncio-mqtt`
 
 ### Note for Windows users
 
-Since Python 3.8, the default asyncio event loop is the `ProactorEventLoop`. Said loop [doesn't support the `add_reader` method](https://docs.python.org/3/library/asyncio-platforms.html#windows) that is required by _asyncio-mqtt_. Please switch to an event loop that supports the `add_reader` method such as the built-in `SelectorEventLoop`:
+Since Python 3.8, the default asyncio event loop is the `ProactorEventLoop`. Said loop [doesn't support the `add_reader` method](https://docs.python.org/3/library/asyncio-platforms.html#windows) that is required by asyncio-mqtt. Please switch to an event loop that supports the `add_reader` method such as the built-in `SelectorEventLoop`:
 
 ```python
 # Change to the "Selector" event loop
@@ -97,11 +99,11 @@ The changelog lives in the [CHANGELOG.md](https://github.com/sbtinstruments/asyn
 
 ## Related projects
 
-Is _asyncio-mqtt_ not what you're looking for? There are a few other clients you can try:
+Is asyncio-mqtt not what you're looking for? There are a few other clients you can try:
 
 - [paho-mqtt](https://github.com/eclipse/paho.mqtt.python) — Own protocol implementation. Synchronous.<br>![GitHub stars](https://img.shields.io/github/stars/eclipse/paho.mqtt.python) ![license](https://img.shields.io/github/license/eclipse/paho.mqtt.python)
 - [gmqtt](https://github.com/wialon/gmqtt) — Own protocol implementation. Asynchronous.<br>![GitHub stars](https://img.shields.io/github/stars/wialon/gmqtt) ![license](https://img.shields.io/github/license/wialon/gmqtt)
 - [fastapi-mqtt](https://github.com/sabuhish/fastapi-mqtt) — Asynchronous wrapper around gmqtt. Simplifies integration in your FastAPI application.<br>![GitHub stars](https://img.shields.io/github/stars/sabuhish/fastapi-mqtt) ![license](https://img.shields.io/github/license/sabuhish/fastapi-mqtt)
 - [amqtt](https://github.com/Yakifo/amqtt) — Own protocol implementation. Asynchronous. Includes a broker.<br>![GitHub stars](https://img.shields.io/github/stars/Yakifo/amqtt) ![license](https://img.shields.io/github/license/Yakifo/amqtt)
 - [mqttools](https://github.com/eerimoq/mqttools) — Own protocol implementation. Asynchronous.<br>![GitHub stars](https://img.shields.io/github/stars/eerimoq/mqttools) ![license](https://img.shields.io/github/license/eerimoq/mqttools)
-- [trio-paho-mqtt](https://github.com/bkanuka/trio-paho-mqtt) — Asynchronous wrapper around paho-mqtt (similar to _asyncio-mqtt_). Based on trio instead of asyncio.<br>![GitHub stars](https://img.shields.io/github/stars/bkanuka/trio-paho-mqtt) ![license](https://img.shields.io/github/license/bkanuka/trio-paho-mqtt)
+- [trio-paho-mqtt](https://github.com/bkanuka/trio-paho-mqtt) — Asynchronous wrapper around paho-mqtt (similar to asyncio-mqtt). Based on trio instead of asyncio.<br>![GitHub stars](https://img.shields.io/github/stars/bkanuka/trio-paho-mqtt) ![license](https://img.shields.io/github/license/bkanuka/trio-paho-mqtt)

docs/filtering-messages.md

@@ -15,7 +15,7 @@
 :maxdepth: 2
 
 configuring-the-client
-filtering-messages
+publishing-and-subscribing
 sharing-the-connection
 listening-without-blocking
 reconnecting

docs/index.md

@@ -0,0 +1,88 @@
+# Publishing and subscribing
+
+Let's see a minimal working example of publishing a message:
+
+```python
+import asyncio
+import asyncio_mqtt as aiomqtt
+
+
+async def main():
+    async with aiomqtt.Client("test.mosquitto.org") as client:
+        await client.publish("humidity/outside", payload=0.38)
+
+asyncio.run(main())
+```
+
+For subscribing and listening to messages, a minimal working example looks like this:
+
+```python
+import asyncio
+import asyncio_mqtt as aiomqtt
+
+
+async def main():
+    async with aiomqtt.Client("test.mosquitto.org") as client:
+        async with client.messages() as messages:
+            await client.subscribe("humidity/#")
+            async for message in messages:
+                print(message.payload)
+
+
+asyncio.run(main())
+```
+
+## Payload encoding
+
+Message payloads can be of types `int`, `float`, `str`, `bytes`, `bytearray`, and `None`.
+
+asyncio-mqtt (or more precisely, paho-mqtt) automatically converts `int` and `float` payloads to `str`. If you want to send a true `int` or `float`, you can use [`struct.pack()`](https://docs.python.org/3/library/struct.html) to encode it as a `bytes` object.
+
+If no payload is given or if it's set to `None`, a zero-length payload will be sent.
+
+All other types you'll have to encode yourself. For example, if you want to send a `dict` as JSON, you can use `json.dumps()` (which returns a `str`):
+
+```python
+import asyncio
+import asyncio_mqtt as aiomqtt
+import json
+
+
+async def main():
+    async with aiomqtt.Client("test.mosquitto.org") as client:
+        await client.publish("humidity/outside", payload=json.dumps({"humidity": 0.38}))
+
+
+asyncio.run(main())
+```
+
+On the receiving end, you can then use `json.loads()` to decode the JSON string back into a `dict`.
+
+## Filtering messages
+
+Imagine you're measuring temperature and humidity on the outside and inside, and our topics look like this: `temperature/outside`. You want to receive all types of measurements but handle them differently.
+
+asyncio-mqtt provides `Topic.matches()` to make this easy:
+
+```python
+import asyncio
+import asyncio_mqtt as aiomqtt
+
+
+async def main():
+    async with aiomqtt.Client("test.mosquitto.org") as client:
+        async with client.messages() as messages:
+            await client.subscribe("#")
+            async for message in messages:
+                if message.topic.matches("humidity/outside"):
+                    print(f"[humidity/outside] {message.payload}")
+                if message.topic.matches("+/inside"):
+                    print(f"[+/inside] {message.payload}")
+                if message.topic.matches("temperature/#"):
+                    print(f"[temperature/#] {message.payload}")
+
+
+asyncio.run(main())
+```
+
+Note that in our example, messages to `temperature/inside` are handled twice!

docs/publishing-and-subscribing.md

@@ -67,4 +67,4 @@ Managing a connection by calling `connect` and `disconnect` directly is a bit tr
 
 Context managers take care of all connection and disconnection logic for you, in a way that makes it very difficult to shoot yourself in the foot. They are a lot easier and less error-prone to use than `connect`/`disconnect`.
 
-Supporting both context managers and manual `connect`/`disconnect` would add a lot of complexity to _asyncio-mqtt_. To keep maintainer burden manageable, we focus only on the preferred option: context managers.
+Supporting both context managers and manual `connect`/`disconnect` would add a lot of complexity to asyncio-mqtt. To keep maintainer burden manageable, we focus only on the preferred option: context managers.