docs: Add topic tags and various improvements

README.md

@@ -48,7 +48,8 @@ Some examples of what you can build with Plugboard include:
 - A **command line interface** for executing models;
 - Built to handle the **data intensive simulation** requirements of industrial process applications;
 - Modern implementation with **Python 3.12 and above** based around **asyncio** with complete type annotation coverage;
-- Built-in integrations for **loading/saving data** from cloud storage and SQL databases.
+- Built-in integrations for **loading/saving data** from cloud storage and SQL databases;
+- **Detailed logging** of component inputs, outputs and state for monitoring and process mining or surrogate modelling use-cases.
 
 ## 🔌 Installation
 
@@ -63,7 +64,7 @@ Support for parallelisation can be installed using `plugboard[ray]`.
 
 ## 🚀 Usage
 
-Plugboard is built to help you with two things: defining process models, and executing those models. There are two main ways to interact with plugboard: via the Python API; or, via the CLI using model definitions saved in yaml or json format.
+Plugboard is built to help you with two things: defining process models, and executing those models. There are two main ways to interact with plugboard: via the Python API; or, via the CLI using model definitions saved in yaml format.
 
 ### Building models with the Python API
 
@@ -134,7 +135,7 @@ flowchart LR
 
 ### Executing pre-defined models on the CLI
 
-In many cases, we want to define components once, with suitable parameters, and then use them repeatedly in different simulations. Plugboard enables this workflow with model specification files in yaml or json format. Once the components have been defined, the simple model above can be represented with a yaml file like so.
+In many cases, we want to define components once, with suitable parameters, and then use them repeatedly in different simulations. Plugboard enables this workflow with model specification files in yaml format. Once the components have been defined, the simple model above can be represented as follows.
 ```yaml
 # my-model.yaml
 plugboard:
@@ -161,21 +162,20 @@ plugboard process run my-model.yaml
 
 ## 📖 Documentation
 
-For more information including a detailed API reference and step-by-step usage examples, refer to the [documentation site](https://docs.plugboard.dev). We recommend diving into the [tutorials](https://docs.plugboard.dev/examples/tutorials/hello-world/) for a step-by-step to getting started.
+For more information including a detailed API reference and step-by-step usage examples, refer to the [documentation site](https://docs.plugboard.dev). We recommend diving into the [tutorials](https://docs.plugboard.dev/latest/examples/tutorials/hello-world/) for a step-by-step to getting started.
 
 ## 🐾 Roadmap
 
 Plugboard is under active development, with new features in the works:
 
-- Detailed logging of component inputs, outputs and state for monitoring and process mining or surrogate modelling use-cases.
 - Support for strongly typed data messages and validation based on pydantic.
 - Support for different parallelisation patterns such as: single-threaded with coroutines, single-host multi process, or distributed with Ray in Kubernetes.
 - Data exchange between components with popular messaging technologies like RabbitMQ and Google Pub/Sub.
 - Support for different message exchange patterns such as: one-to-one, one-to-many, many-to-one etc via a broker; or peer-to-peer with http requests.
 
 ## 👋 Contributions
 
-Contributions are welcomed and warmly received! For bug fixes and smaller feature requests feel free to open an issue on this repo. For any larger changes please get in touch with us to discuss first. More information for developers can be found in [the contributing section](https://docs.plugboard.dev/contributing/) of the docs.
+Contributions are welcomed and warmly received! For bug fixes and smaller feature requests feel free to open an issue on this repo. For any larger changes please get in touch with us to discuss first. More information for developers can be found in [the contributing section](https://docs.plugboard.dev/latest/contributing/) of the docs.
 
 ## ⚖️ Licence
 

docs/examples/tutorials/.meta.yml

@@ -0,0 +1,2 @@
+tags:
+  - tutorial

docs/examples/tutorials/more-components.md

@@ -1,3 +1,9 @@
+---
+tags:
+  - logging
+  - llm
+  - io
+---
 Plugboard's [`Component`][plugboard.component.Component] objects can run anything you can code in Python. This includes:
 
 * Using your own or third-party Python packages;
@@ -54,6 +60,9 @@ We can now define a component to query a weather API and get temperature and win
 --8<-- "examples/tutorials/003_more_components/hello_llm.py:weather"
 ```
 
+!!! info
+    See how we used `self._logger` to record log messages. All Plugboard [`Component`][plugboard.component.Component] objects have a [structlog](https://www.structlog.org/) logger on the `_logger` attribute. See [configuration](../../../usage/configuration/) for more information on configuring the logging.
+
 ### Putting it all together
 
 As usual, we can link all our components together in a [`LocalProcess`][plugboard.process.Process] and run them as follows:

docs/examples/tutorials/running-in-parallel.md

@@ -1,3 +1,7 @@
+---
+tags:
+  - ray
+---
 Up until now we have running all our models in a single computational process. This is perfectly sufficient for simple models, or when your components can make use of [Python's asyncio](https://docs.python.org/3/library/asyncio.html) to avoid blocking.
 
 As your models get larger and more computationally intensive you may benefit from running parts of the model in parallel. Plugboard integrates with the [Ray](https://docs.ray.io/) framework, allowing you to split your computation across multiple CPU cores, or even across nodes in a [Ray cluster](https://docs.ray.io/en/latest/cluster/getting-started.html).

docs/usage/key-concepts.md

@@ -19,7 +19,7 @@ When implementing your own components, you will need to:
 * Specify its inputs and ouputs using an [`IOController`][plugboard.component.IOController];
 * Define a `step()` method the executes the main logic of your component for a single step; and
 * Optionally define an `init()` method to do any required preparatory steps before the model in run.
-* In the case of event based models, define custom `Event` subclasses and corresponding event handler methods decorated with `Event.handler`.
+* In the case of event based models, define custom [`Event`][plugboard.events.Event] subclasses and corresponding event handler methods decorated with `Event.handler`.
 
 ### Connectors
 
@@ -42,7 +42,7 @@ graph LR;
     A(Load data)-->D(Record output);
 ```
 
-For models with explicitly declared input and output fields, connectors for each input-output pair must be defined explicitly using one of the `Connector` implementations. Connectors required for any events used in the model will be created for you automatically. 
+For models with explicitly declared input and output fields, connectors for each input-output pair must be defined explicitly using one of the [`Connector`][plugboard.connector.Connector] implementations. Connectors required for any events used in the model will be created for you automatically. 
 
 ### Processes
 

docs/usage/topics.md

@@ -0,0 +1,5 @@
+# Topic index
+
+To find information on a specific topic, you can look for pages under one of the tags below.
+
+<!-- material/tags -->

examples/demos/llm/.meta.yml

@@ -0,0 +1,2 @@
+tags:
+  - llm

examples/demos/llm/002_bluesky_websocket/.meta.yml

@@ -0,0 +1,3 @@
+tags:
+  - io
+  - streaming

examples/demos/physics-models/.meta.yml

@@ -0,0 +1,2 @@
+tags:
+  - physics-models

examples/tutorials/003_more_components/hello_llm.py

@@ -1,4 +1,4 @@
-"""Simple hello world example."""
+"""Simple LLM example."""
 
 # fmt: off
 import asyncio
@@ -36,8 +36,12 @@ async def step(self) -> None:
         )
         try:
             response.raise_for_status()
-        except httpx.HTTPStatusError as e:
-            print(f"Error querying weather API: {e}")
+        except httpx.HTTPStatusError:
+            self._logger.error(
+                "Error querying weather API",
+                code=response.status_code,
+                message=response.text,
+            )
             return
         data = response.json()
         self.temperature = data["current"]["temperature_2m"]

mkdocs.yaml

@@ -34,6 +34,8 @@ plugins:
 - mike:
     alias_type: symlink
     canonical_version: latest
+- meta
+- tags
 
 markdown_extensions:
 - admonition
@@ -112,6 +114,7 @@ nav:
     - Running in parallel: examples/tutorials/running-in-parallel.md
     - Event-driven models: examples/tutorials/event-driven-models.md
   - Configuration: usage/configuration.md
+  - Topics: usage/topics.md
 - Demos:
   - Fundamentals:
     - Simple model: examples/demos/fundamentals/001_simple_model/simple-model.ipynb

plugboard/utils/logging.py

@@ -18,7 +18,7 @@ def _is_ipython() -> bool:
 
 
 def _serialiser(obj: _t.Any, default: _t.Callable | None) -> bytes:
-    return json.encode(obj)
+    return json.encode(obj, enc_hook=default)
 
 
 def configure_logging(settings: Settings) -> None:

pyproject.toml

@@ -45,6 +45,7 @@ websockets = ["websockets>=14.2"]
 [dependency-groups]
 dev = [
     "ipython~=8.26",
+    "ipywidgets>=8.1.5",
     "jupyterlab~=4.2",
     "mypy~=1.11",
     "nbstripout~=0.8",