Class attributes documentation #1914
Description
Class attributes documentation in dodal docs is a mess.
Current approach is either to declare them explicitly (google-docs style) or not bother at all. If they are declared explicitly in class docstring, e.g.
"""A StandardReadable device that represents a synchrotron facility, providing access to
various synchrotron parameters and operational status.
Args:
signal_prefix (str, optional): Beamline part of PV. Defaults to Prefix.SIGNAL.
status_prefix (str, optional): Status part of PV. Defaults to Prefix.STATUS.
Attributes:
current (SignalR[float]): Read-only signal for the synchrotron beam current.
energy (SignalR[float]): Read-only signal for the beam energy.
"""
This results in a formatted html without any header stating these are Attributes:
If they are not stated in a docstring then they might be automatically parsed by sphinx and appear in Attributes section of class docs but not reliably. Attributes will be ignored if they are created inside with block, e.g.
with self.add_children_as_readables():
self.current = epics_signal_r(float, signal_prefix + Suffix.SIGNAL)
self.energy = epics_signal_r(float, status_prefix + Suffix.BEAM_ENERGY)
Attributes that were created using declarative approach like with pydantic models will be parsed and appear in Attributes section of class docs
class LookupTableColumnConfig(BaseModel):
"""Configuration on how to process a csv file columns into a LookupTable data
model.
"""
source: A[
Source | None,
Field(
description="If not None, only process the row if the source column name match the value."
),
] = None
mode: A[str, Field(description="Polarisation mode column name.")] = "Mode"
min_energy: A[str, Field(description="Minimum energy column name.")] = "MinEnergy"
max_energy: A[str, Field(description="Maximum energy column name.")] = "MaxEnergy"
And sometimes it can be both, like in dodal.devices.temperture_controller.Lakeshore:
