DiamondLightSource / DiamondLightSource/dodal

Class attributes documentation

Open
#1,914 1 comment 0 reactions 0 assignees View on GitHub
Docsathon documentation
Dominant language
Python
Stars
5
Forks
13
Avg merge
3d 2h
Merged PRs (30d)
10

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:

Image

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"
```

Image

And sometimes it can be both, like in dodal.devices.temperture_controller.Lakeshore:

Image

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.