Improve README.md for Better Project Discoverability

README.md

@@ -6,18 +6,85 @@
 
 ## Introduction
 
-A highlevel interface for the dispatch API.
+The `frequenz-dispatch` library provides a high-level Python interface for 
+interacting with the Frequenz Dispatch API. This library enables you to 
+manage and monitor dispatch operations in microgrids, including lifecycle 
+events and running status changes of dispatch operations.
 
-See [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) for more information.
+The main entry point is the [`Dispatcher`][dispatcher-class] class, which 
+provides channels for receiving dispatch lifecycle events and running status 
+updates, allowing you to build reactive applications that respond to dispatch 
+state changes.
 
-## Usage
+## Supported Platforms
+
+The following platforms are officially supported (tested):
 
-The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher), the main entry point for the API, provides two channels:
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 24.04
+- **Architectures:** amd64, arm64
 
-* [Lifecycle events](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events): A channel that sends a message whenever a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted.
-* [Running status change](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change): Sends a dispatch message whenever a dispatch is ready to be executed according to the schedule or the running status of the dispatch changed in a way that could potentially require the actor to start, stop or reconfigure itself.
+## Installation
+
+### Using pip
+
+You can install the package from PyPI:
+
+```bash
+python3 -m pip install frequenz-dispatch
+```
 
-### Example using the running status change channel
+### Using pyproject.toml
+
+Add the dependency to your `pyproject.toml` file:
+
+```toml
+[project]
+dependencies = [
+    "frequenz-dispatch >= 0.10.1, < 0.11",
+]
+```
+
+> [!NOTE]
+> We recommend pinning the dependency to the latest version for programs,
+> like `"frequenz-dispatch == 0.10.1"`, and specifying a version range
+> spanning one major version for libraries, like
+> `"frequenz-dispatch >= 0.10.1, < 0.11"`. We follow [semver](https://semver.org/).
+
+## Quick Start
+
+Here's a minimal example to get you started:
+
+```python
+import os
+from frequenz.dispatch import Dispatcher
+
+async def main():
+    # Configure connection to dispatch API
+    url = os.getenv("DISPATCH_API_URL", "grpc://your-dispatch-url.com")
+    key = os.getenv("DISPATCH_API_KEY", "your-api-key")
+    microgrid_id = 1
+
+    # Create and use the dispatcher
+    async with Dispatcher(
+        microgrid_id=microgrid_id,
+        server_url=url,
+        key=key,
+    ) as dispatcher:
+        # Your dispatch logic here
+        print("Dispatcher ready!")
+```
+
+The [`Dispatcher` class][dispatcher-class] provides two channels:
+
+* [Lifecycle events][lifecycle-events]: A channel that sends a message whenever
+  a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted.
+* [Running status change][running-status-change]: Sends a dispatch message
+  whenever a dispatch is ready to be executed according to the schedule or the
+  running status of the dispatch changed in a way that could potentially
+  require the actor to start, stop or reconfigure itself.
+
+### Example managing actors with dispatch events
 
 ```python
 import os
@@ -26,12 +93,16 @@ from datetime import timedelta
 
 from frequenz.dispatch import Dispatcher, DispatchInfo, MergeByType
 
-async def create_actor(dispatch: DispatchInfo, receiver: Receiver[DispatchInfo]) -> Actor:
+async def create_actor(
+    dispatch: DispatchInfo, receiver: Receiver[DispatchInfo]
+) -> Actor:
     return MagicMock(dispatch=dispatch, receiver=receiver)
 
 async def run():
-    url = os.getenv("DISPATCH_API_URL", "grpc://dispatch.url.goes.here.example.com")
-    key  = os.getenv("DISPATCH_API_KEY", "some-key")
+    url = os.getenv(
+        "DISPATCH_API_URL", "grpc://dispatch.url.goes.here.example.com"
+    )
+    key = os.getenv("DISPATCH_API_KEY", "some-key")
 
     microgrid_id = 1
 
@@ -50,13 +121,14 @@ async def run():
         await dispatcher
 ```
 
-## Supported Platforms
+[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher
+[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events
+[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change
 
-The following platforms are officially supported (tested):
+## Documentation
 
-- **Python:** 3.11
-- **Operating System:** Ubuntu Linux 20.04
-- **Architectures:** amd64, arm64
+For complete API documentation, examples, and advanced usage patterns, see
+[the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch).
 
 ## Contributing