Skip to content

docs: Update docs to match code - #1773

Open
DiamondJoseph wants to merge 3 commits into
DiamondLightSource:mainfrom
DiamondJoseph:update-docs-to-match-code
Open

DiamondJoseph wants to merge 3 commits into
DiamondLightSource:mainfrom
DiamondJoseph:update-docs-to-match-code

Conversation

@DiamondJoseph

Copy link
Copy Markdown
Contributor

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.md

  • Replaces the "Disallowed Plan arguments" section, which said positional-only and variadic arguments were unsupported. Since feat: Support *args and **kwargs in plan definitions #1715 and fix: duplicate empty kwargs #1720 every parameter kind works, so the page now explains how the args and params of a request bind to a plan's signature.
  • States that every parameter, including *args and **kwargs, needs a type annotation, and that an unannotated one stops the whole environment from loading.
  • Warns that a value for a parameter annotated Any is passed through as plain JSON data and is never resolved to a device.
  • Adds a section on DeviceType | str for devices that may not be available. The device type must come first in the union, and the plan must check with isinstance at its start and log the outcome.

docs/explanations/api-version.md

  • The page said not to update docs/reference/openapi.yaml, while test_schema_updated requires it to match the generated schema. It now says to regenerate the file with blueapi schema -u and never to edit it by hand.

docs/how-to/run-with-dev.md

  • Rewritten for the devcontainer. The old page described activating a venv and a "Worker Service" debug configuration, neither of which exists any more.

Examples and tests

  • invalid_plan_args.py showed a positional-only plan, which is now valid. It shows an unannotated variadic plan instead, and its test asserts the ValueError raised when the module is loaded.
  • plan_argument_kinds.py and plan_optional_device.py are new examples included in the plans page and covered by test_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.png still shows a configuration named "Worker Service". The how-to links to it with a note that the name differs. It needs retaking.
  • The how-to says services started on the host are reachable on localhost inside the devcontainer on Linux. That follows from --net=host in devcontainer.json and was not tested.
  • Run locally: the unit tests except the helm-dependent ones (no helm on 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:

  1. Run tox -e docs and read the three pages under build/html.
  2. Run pytest tests/unit_tests/test_example_code.py and confirm the ten tests pass.
  3. Open the devcontainer and follow docs/how-to/run-with-dev.md from "Start the Server" to confirm the steps and launch configuration names match.

Checks for reviewer

  • Would the PR title make sense to a user on a set of release notes

🤖 Generated with Claude Code

Assisted-by: Claude Fable 5.2 via Claude Code

Joseph Ware and others added 3 commits November 16, 2026 18:05
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>
@DiamondJoseph
DiamondJoseph requested a review from a team as a code owner November 16, 2026 18:10
@DiamondJoseph DiamondJoseph changed the title Update docs to match code docs: Update docs to match code Nov 16, 2026
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.30%. Comparing base (1e761f9) to head (dc93995).

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant