Replace PlanModel using the __doc__ of a plan with using Annotated pydantic fields

[DiamondJoseph]

blueapi controller plans returns a description of the plans that are available in the context. Currently this comes from the docstring of the plan function. This should get also/instead(?) the description of the Pydantic model that is constructed, including information about the fields of the plan: defaults, types, limits etc.

Using Annotated allows us to have this information presented as part of the json schema, and reduce the amount of information required in the docstring.

[DiamondJoseph]

e.g.

def stp_snapshot(
    detectors: list[Readable],
    temperature: Movable = inject("sample_temperature"),
    pressure: Movable = inject("sample_pressure"),
) -> MsgGenerator:
    """
    Moves devices for pressure and temperature (defaults fetched from the context)
    and captures a single frame from a collection of devices

    Args:
        detectors (List[Readable]): A list of devices to read while the sample is at STP
        temperature (Optional[Movable]): A device controlling temperature of the sample,
            defaults to fetching a device name "sample_temperature" from the context
        pressure (Optional[Movable]): A device controlling pressure on the sample,
            defaults to fetching a device name "sample_pressure" from the context
    Returns:
        MsgGenerator: Plan
    Yields:
        Iterator[MsgGenerator]: Bluesky messages
    """

then becomes

def stp_snapshot(
    detectors: set[Readable] = Annotated[
        Field(set[Readable], min_length=1), "Devices to read while the sample is at STP"
    ],
    temperature: Movable = Annotated[
        inject("sample_temperature"), "A device controlling temperature of the sample"
    ],
    pressure: Movable = Annotated[
        inject("sample_pressue"), "A device controlling pressure of the sample"
    ],
) -> MsgGenerator:
    """
    Moves devices for pressure and temperature (defaults fetched from the context)
    and captures a single frame from a collection of devices
    """

And the information about the detector minimum length (bad example) gets propagated through.

[DiamondJoseph]

This must also propagate the value of any defaults into the json schema.

[callumforrester]

I'm not entirely happy with this, since we want to use standard tools/methods as far as possible and make the process of migrating a plan that someone wrote in their IPython environment to blueapi as painless as possible. People are more likely to have plans with standard docstrings than annotated arguments so we're just adding an extra step here.

Could we add some special handling to parse docstrings and get the results into a JSON schema?

[DiamondJoseph]

As discussed here, we don't actually get any extra info from Annotated or Fields at the moment.

Given there's at least 3 different standard forms of docstrings, I think providing a default base level of just displaying the docstring and type annotation info, and choosing one supported form for rich info is reasonable.

[callumforrester]

@DiamondJoseph can this be closed?