docs: initial API docs

Author: urish

docs/index.md

@@ -1,3 +1,62 @@
 # Wokwi Python Client Library
 
-Welcome! These docs will eventually cover installation, quickstart examples, and the full API reference.
+Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
+
+## Features
+
+- Connect to the Wokwi Simulator from Python
+- Upload diagrams and firmware files
+- Start, pause, resume, and restart simulations
+- Monitor serial output asynchronously
+- Fully type-annotated and easy to use with asyncio
+
+## Installation
+
+Requires Python ≥ 3.9
+
+```bash
+pip install wokwi-client
+```
+
+## Getting an API Token
+
+Get your API token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashboard/ci).
+
+## Quickstart Example
+
+```python
+import asyncio
+import os
+from wokwi_client import WokwiClient, GET_TOKEN_URL
+
+
+async def main():
+    token = os.getenv("WOKWI_CLI_TOKEN")
+    if not token:
+        raise SystemExit(
+            f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
+        )
+
+    client = WokwiClient(token)
+    await client.connect()
+    await client.upload_file("diagram.json")
+    await client.upload_file("firmware.bin")
+    await client.upload_file("firmware.elf")
+    await client.start_simulation(firmware="firmware.bin", elf="firmware.elf")
+    serial_task = asyncio.create_task(
+        client.serial_monitor_cat()
+    )  # Stream serial output
+    await client.wait_until_simulation_time(10)  # Run simulation for 10 seconds
+    serial_task.cancel()
+    await client.disconnect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+See the [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py) for a full example including serial monitoring.
+
+## API Reference
+
+See the [API Reference](reference/wokwi_client.md) for full details.

src/wokwi_client/__init__.py

@@ -1,3 +1,11 @@
+"""
+Wokwi Python Client Library
+
+Typed, asyncio-friendly Python SDK for the Wokwi Simulation API.
+
+Provides the WokwiClient class for connecting to, controlling, and monitoring Wokwi simulations from Python.
+"""
+
 # SPDX-FileCopyrightText: 2025-present CodeMagic LTD
 #
 # SPDX-License-Identifier: MIT

src/wokwi_client/client.py

@@ -16,40 +16,142 @@
 
 
 class WokwiClient:
+    """
+    Asynchronous client for the Wokwi Simulation API.
+
+    This class provides methods to connect to the Wokwi simulator, upload files, control simulations,
+    and monitor serial output. It is designed to be asyncio-friendly and easy to use in Python scripts
+    and applications.
+    """
+
     version: str
     last_pause_nanos: int
 
     def __init__(self, token: str, server: Optional[str] = None):
+        """
+        Initialize the WokwiClient.
+
+        Args:
+            token: API token for authentication (get from https://wokwi.com/dashboard/ci).
+            server: Optional custom server URL. Defaults to the public Wokwi server.
+        """
         self.version = get_version()
         self._transport = Transport(token, server or DEFAULT_WS_URL)
         self.last_pause_nanos = 0
         self._transport.add_event_listener("sim:pause", self._on_pause)
         self._pause_queue = EventQueue(self._transport, "sim:pause")
 
     async def connect(self) -> dict[str, Any]:
+        """
+        Connect to the Wokwi simulator server.
+
+        Returns:
+            A dictionary with server information (e.g., version).
+        """
         return await self._transport.connect()
 
     async def disconnect(self) -> None:
+        """
+        Disconnect from the Wokwi simulator server.
+        """
         await self._transport.close()
 
     async def upload(self, name: str, content: bytes) -> ResponseMessage:
+        """
+        Upload a file to the simulator from bytes content.
+
+        Args:
+            name: The name to use for the uploaded file.
+            content: The file content as bytes.
+
+        Returns:
+            The response message from the server.
+        """
         return await upload(self._transport, name, content)
 
     async def upload_file(
         self, filename: str, local_path: Optional[Path] = None
     ) -> ResponseMessage:
+        """
+        Upload a local file to the simulator.
+
+        Args:
+            filename: The name to use for the uploaded file.
+            local_path: Optional path to the local file. If not provided, uses filename as the path.
+
+        Returns:
+            The response message from the server.
+        """
         return await upload_file(self._transport, filename, local_path)
 
-    async def start_simulation(self, **kwargs: Any) -> ResponseMessage:
-        return await start(self._transport, **kwargs)
+    async def start_simulation(
+        self,
+        firmware: str,
+        elf: str,
+        pause: bool = False,
+        chips: list[str] = [],
+    ) -> ResponseMessage:
+        """
+        Start a new simulation with the given parameters.
+
+        The firmware and ELF files must be uploaded to the simulator first using the
+        `upload()` or `upload_file()` methods. The firmware and ELF files are required
+        for the simulation to run.
+
+        The optional `chips` parameter can be used to load custom chips into the simulation.
+        For each custom chip, you need to upload two files:
+        - A JSON file with the chip definition, called `<chip_name>.chip.json`.
+        - A binary file with the chip firmware, called `<chip_name>.chip.bin`.
+
+        For example, to load the `inverter` chip, you need to upload the `inverter.chip.json`
+        and `inverter.chip.bin` files. Then you can pass `["inverter"]` to the `chips` parameter,
+        and reference it in your diagram.json file by adding a part with the type `chip-inverter`.
+
+        Args:
+            firmware: The firmware binary filename.
+            elf: The ELF file filename.
+            pause: Whether to start the simulation paused (default: False).
+            chips: List of custom chips to load into the simulation (default: empty list).
+
+        Returns:
+            The response message from the server.
+        """
+        return await start(
+            self._transport,
+            firmware=firmware,
+            elf=elf,
+            pause=pause,
+            chips=chips,
+        )
 
     async def pause_simulation(self) -> ResponseMessage:
+        """
+        Pause the running simulation.
+
+        Returns:
+            The response message from the server.
+        """
         return await pause(self._transport)
 
     async def resume_simulation(self, pause_after: Optional[int] = None) -> ResponseMessage:
+        """
+        Resume the simulation, optionally pausing after a given number of nanoseconds.
+
+        Args:
+            pause_after: Number of nanoseconds to run before pausing again (optional).
+
+        Returns:
+            The response message from the server.
+        """
         return await resume(self._transport, pause_after)
 
     async def wait_until_simulation_time(self, seconds: float) -> None:
+        """
+        Pause and resume the simulation until the given simulation time (in seconds) is reached.
+
+        Args:
+            seconds: The simulation time to wait for, in seconds.
+        """
         await pause(self._transport)
         remaining_nanos = seconds * 1e9 - self.last_pause_nanos
         if remaining_nanos > 0:
@@ -58,9 +160,21 @@ async def wait_until_simulation_time(self, seconds: float) -> None:
             await self._pause_queue.get()
 
     async def restart_simulation(self, pause: bool = False) -> ResponseMessage:
+        """
+        Restart the simulation, optionally starting paused.
+
+        Args:
+            pause: Whether to start the simulation paused (default: False).
+
+        Returns:
+            The response message from the server.
+        """
         return await restart(self._transport, pause)
 
     async def serial_monitor_cat(self) -> None:
+        """
+        Print serial monitor output to stdout as it is received from the simulation.
+        """
         async for line in monitor_lines(self._transport):
             print(line.decode("utf-8"), end="", flush=True)