docs: Add topic tags and various improvements

[toby-coleman]

Summary

Various improvements to the docs, including topic tags. Migrated from #117.

Changes

• Adds tags and a topic index to the docs for improved navigation.
• Minor fixes and improvements to the README.
• Small fix to the logger code to allow it to serialise types not supported by msgspec, e.g. Pydantic objects.

[gemini-code-assist]

Hello @toby-coleman, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

This pull request focuses on improving the Plugboard documentation by adding topic tags for better navigation and making minor fixes and improvements to the README. It also includes a small fix to the logger code to allow it to serialize types not supported by msgspec, such as Pydantic objects. The addition of topic tags should make it easier for users to find relevant information in the documentation.

Highlights

• Documentation: Adds topic tags and a topic index to the documentation for improved navigation. This includes adding meta and tags plugins to mkdocs.yaml.
• README: Minor fixes and improvements to the README, such as updating the documentation link and removing the mention of JSON format for model definitions.
• Logging: Fixes the logger code to allow it to serialize types not supported by msgspec, such as Pydantic objects, by adding enc_hook to the json.encode call.

Changelog

Click here to see the changelog

• README.md
  • Adds detailed logging to the list of Plugboard features.
  • Removes 'json' as a supported format for CLI model definitions, leaving only 'yaml'.
  • Updates the documentation link to point to the 'latest' version.
  • Removes 'Detailed logging of component inputs, outputs and state for monitoring and process mining or surrogate modelling use-cases.' from the roadmap, as it is now implemented.
• docs/examples/tutorials/.meta.yml
  • Adds a 'tutorial' tag to the directory.
• docs/examples/tutorials/more-components.md
  • Adds tags 'logging', 'llm', and 'io' to the document.
  • Adds an info box explaining the use of self._logger for logging messages.
• docs/examples/tutorials/running-in-parallel.md
  • Adds the 'ray' tag to the document.
• docs/usage/key-concepts.md
  • Adds a link to the Event class in the sentence about event-based models.
  • Adds a link to the Connector class in the sentence about connectors.
• docs/usage/topics.md
  • Creates a new page for topic indexing, including a placeholder for the material tags.
• examples/demos/llm/.meta.yml
  • Adds the 'llm' tag to the directory.
• examples/demos/llm/002_bluesky_websocket/.meta.yml
  • Adds the 'io' and 'streaming' tags to the directory.
• examples/demos/physics-models/.meta.yml
  • Adds the 'physics-models' tag to the directory.
• examples/tutorials/003_more_components/hello_llm.py
  • Changes the docstring from "Simple hello world example." to "Simple LLM example."
  • Replaces print with self._logger.error when handling HTTPStatusError.
• mkdocs.yaml
  • Adds the meta and tags plugins.
  • Adds a navigation link to the 'Topics' page.
• plugboard/utils/logging.py
  • Adds the enc_hook argument to the json.encode call in the _serialiser function.
• pyproject.toml
  • Adds ipywidgets>=8.1.5 to the dev dependencies.
• uv.lock
  • Updates click dependency marker from sys_platform == 'win32' to platform_system == 'Windows'.
  • Updates ipykernel dependency marker from sys_platform == 'darwin' to platform_system == 'Darwin'.
  • Adds ipywidgets as a dependency.
  • Adds jupyterlab-widgets as a dependency.
  • Adds widgetsnbextension as a dependency.
  • Updates mkdocs dependency marker from sys_platform == 'win32' to platform_system == 'Windows'.
  • Adds ipywidgets to the dev dependencies in [package.dev-dependencies].
  • Adds ipywidgets to the dev dependencies in [package.metadata.requires-dev].
  • Updates portalocker dependency marker from sys_platform == 'win32' to platform_system == 'Windows'.
  • Updates tqdm dependency marker from sys_platform == 'win32' to platform_system == 'Windows'.
  • Adds widgetsnbextension as a dependency.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

---

A tag for each topic,
A guide through the doc's vast sea,
Knowledge found with ease.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces topic tags to the documentation, improves navigation, and includes minor fixes to the README and logger code. The changes seem well-organized and contribute to the overall usability and maintainability of the project.

Summary of Findings

• Error Handling in WeatherAPI Component: The WeatherAPI component's error handling could be improved by logging more detailed information about the error, such as the status code and response text, to aid in debugging and monitoring.
• Platform Specific Dependency Markers: The dependency markers in uv.lock use sys_platform which is less specific than platform_system. Using platform_system ensures compatibility across different Python implementations.

Merge Readiness

The pull request is almost ready for merging. Addressing the error handling in the WeatherAPI component and updating the dependency markers in uv.lock would improve the robustness and maintainability of the code. I am unable to directly approve this pull request, and recommend that others review and approve this code before merging, especially after the critical and high severity issues are addressed.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!