Repository navigation
Feature: Add config to docstring #440
Description
Description, motivation and use case
Add config of an element to its docstring. It will appear in API documentation, where I would imagine a new user can look for a way to configure the element. In the case of BPM, the config is very close to just the init arguments but for magnets it's a bit more complex
Proposed solution
Add example or template config to the docstring.
Describe alternatives you've considered
An alternative is not to do it and have some other accessible way.
Example
Example of a BPM docstring:
Beam position monitor (BPM) element. Represents a BPM in the accelerator lattice and provides access to its associated readback signals, including horizontal and vertical beam positions, calibration offsets, and mechanical tilt. Parameters ---------- name : str Name of the BPM. lattice_names : str | None, optional Lattice-specific name or names identifying the BPM. description : str | None, optional Description of the BPM. x_pos : str | None, optional Device catalog key for the horizontal beam position. y_pos : str | None, optional Device catalog key for the vertical beam position. x_offset : str | None, optional Device catalog key for the horizontal BPM offset. y_offset : str | None, optional Device catalog key for the vertical BPM offset. tilt : str | None, optional Device catalog key for the BPM tilt. Attributes ---------- positions Read accessor for the horizontal and vertical beam positions, in metres. offset Read/write accessor for the two calibration offsets, in metres. tilt Read/write accessor for the mechanical tilt, in radians. Methods ------- attach(peer, positions, offset, tilt) Attach BPM attributes to a peer. get_pos_devices() Return configured device keys used for position readback. get_tilt_device() Return the configured device key used for tilt access. get_offset_devices() Return configured device keys used for offset control. Configuration file snippet ------- - type: pyaml.bpm.bpm name: BPM_PYAML_NAME lattice_names: NAME_IN_LATTICE_FILE x_pos: TANGO/OR/EPICS/ATTRIBUTE/STRING y_pos: TANGO/OR/EPICS/ATTRIBUTE/STRING x_offset: TANGO/OR/EPICS/ATTRIBUTE/STRING y_offset: TANGO/OR/EPICS/ATTRIBUTE/STRING tilt: TANGO/OR/EPICS/ATTRIBUTE/STRING
@TeresiaOlsson @simoneliuzzo @GamelinAl is this interesting?
Checklist
- I've assigned this issue to a project
- I've @-mentioned relevant people
Activity
TeresiaOlsson commentedon Sep 18, 2026
I'm not entirely sure why the config and the
__init__arguments are not the same already everywhere? I don't think we have any class at the moment where the configuration schema isn't dynamically generated from the constructor. And if that is the case, how can__init__have different arguments that what the configuration needs? And the factory wouldn't work since it just takes the fields in the configuration, removes theclassand passes the rest of the fields to the constructor?But I think it would be nice with an example configuration in the docstring.
simoneliuzzo commentedon Sep 18, 2026
Dear @gubaidulinvadim,
I like the configuration file snippet!
GamelinAl commentedon Sep 18, 2026
This proposal has the advantage of making the configuration quite clear from docstring. I like it.
But as @TeresiaOlsson says, is there any class where the rule conf = arguments is not followed?
If it's the case then I would say it's better to explain this rule at different places in the documentation and in the docstrings.
We could do both your proposal generate twice the work in term of docstrings.
TeresiaOlsson commentedon Sep 18, 2026
I also like it but worry about the maintenance. But on the other hand we have written almost all the docstrings using AI now so maybe it's not a problem? Maybe only thing we need is a reusable prompt which explains what content and format we want for the docstrings and AI might be able to add this part for us too?
GamelinAl commentedon Sep 18, 2026
But they are still written for humans :) so it's better if it's not infinity long
gubaidulinvadim commentedon Sep 18, 2026
I think the docstring does not become too long. The only case where docstring does not match init is I think the magnets that have an underlying model. You can skip the model description and have: