Repository navigation
docs: Update docs to match code - #1773
Open
DiamondJoseph wants to merge 3 commits into
Open
DiamondJoseph wants to merge 3 commits into
DiamondJoseph wants to merge 3 commits into
Conversation
The page told contributors not to update docs/reference/openapi.yaml, but test_schema_updated fails unless the file matches the schema generated from the code. Say to regenerate it with `blueapi schema -u` and never to edit it by hand. Assisted-by: Claude Fable 5.2 via Claude Code Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The plans explanation said positional-only and variadic arguments were not supported. Since DiamondLightSource#1715 and DiamondLightSource#1720 every parameter kind works, so describe how the `args` and `params` of a request bind to a plan. Also document that: - every parameter, including *args and **kwargs, needs a type annotation, and an unannotated one stops the environment loading - a value for a parameter annotated Any is passed through as plain JSON data and is never resolved to a device - `DeviceType | str` passes the device when one is available and the name otherwise, so the plan must check with isinstance early and log The invalid_plan_args example showed a positional-only plan, which is now valid, so it shows an unannotated variadic plan instead. Two new examples are included in the docs and covered by test_example_code.py. Assisted-by: Claude Fable 5.2 via Claude Code Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The guide described activating a venv and a "Worker Service" debug configuration, neither of which exists any more. Describe the devcontainer workflow instead: nothing to activate, the current launch configurations, starting other services from the host and running the checks with just and tox. Assisted-by: Claude Fable 5.2 via Claude Code Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1773 +/- ##
=======================================
Coverage 96.30% 96.30%
=======================================
Files 50 50
Lines 3821 3821
=======================================
Hits 3680 3680
Misses 141 141 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This was referenced Nov 16, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three documentation pages had drifted from the code. This brings them back in line and adds tested examples for the plan argument rules. There is no linked issue.
What changed
docs/explanations/plans.mdargsandparamsof a request bind to a plan's signature.*argsand**kwargs, needs a type annotation, and that an unannotated one stops the whole environment from loading.Anyis passed through as plain JSON data and is never resolved to a device.DeviceType | strfor devices that may not be available. The device type must come first in the union, and the plan must check withisinstanceat its start and log the outcome.docs/explanations/api-version.mddocs/reference/openapi.yaml, whiletest_schema_updatedrequires it to match the generated schema. It now says to regenerate the file withblueapi schema -uand never to edit it by hand.docs/how-to/run-with-dev.mdExamples and tests
invalid_plan_args.pyshowed a positional-only plan, which is now valid. It shows an unannotated variadic plan instead, and its test asserts theValueErrorraised when the module is loaded.plan_argument_kinds.pyandplan_optional_device.pyare new examples included in the plans page and covered bytest_example_code.py. One test pins that the optional-device example receives the device for a known name and the string otherwise, because that depends on how pydantic resolves the union.Things to know
docs/images/debug-vscode.pngstill shows a configuration named "Worker Service". The how-to links to it with a note that the name differs. It needs retaking.localhostinside the devcontainer on Linux. That follows from--net=hostindevcontainer.jsonand was not tested.helmon the machine used), pyright, the ruff and gitleaks hooks on the changed files, and the docs build with warnings as errors. The helm tests and system tests were not run locally.Instructions to reviewer on how to test:
tox -e docsand read the three pages underbuild/html.pytest tests/unit_tests/test_example_code.pyand confirm the ten tests pass.docs/how-to/run-with-dev.mdfrom "Start the Server" to confirm the steps and launch configuration names match.Checks for reviewer
🤖 Generated with Claude Code
Assisted-by: Claude Fable 5.2 via Claude Code