Add docstring to synchrotron class

[Villtord]

Add docstring to synchrotron class.

Instructions to reviewer on how to test:

1. Do thing x
2. Confirm thing y happens

Checks for reviewer

• Would the PR title make sense to a scientist on a set of release notes
• If a new device has been added does it follow the standards
• If changing the API for a pre-existing device, ensure that any beamlines using this device have updated their Bluesky plans accordingly
• Have the connection tests for the relevant beamline(s) been run via dodal connect ${BEAMLINE}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (dffe1f8) to head (b30c45b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1877   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files         312      312           
  Lines       11749    11761   +12     
=======================================
+ Hits        11638    11650   +12     
  Misses        111      111           

☔ View full report in Codecov by Sentry.
📢 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.

[oliwenmandiamond]

"""A StandardReadable device representing a synchrotron facility.

This device provides access to key synchrotron parameters and operational
status information.

Attributes:
current (EpicsSignalR): Read-only signal for the synchrotron beam current.
energy (EpicsSignalR): Read-only signal for the beam energy.
probe (SoftSignalRW): Configurable signal for the probe type.
Defaults to "x-ray".
type (SoftSignalRW): Configurable signal for the synchrotron type.
Defaults to "Synchrotron X-ray Source".
synchrotron_mode (EpicsSignalR): Read-only signal for the current
synchrotron operating mode.
machine_user_countdown (EpicsSignalR): Read-only signal for the
machine user countdown timer.
top_up_start_countdown (EpicsSignalR): Read-only signal for the
top-up start countdown timer.
top_up_end_countdown (EpicsSignalR): Read-only signal for the
top-up end countdown timer.
"""

[Villtord]

Here it is #1914

[DominicOram]

Thanks, I'm not a massive fan of docs like these. Like Read-only signal for the machine user countdown timer. gives me no additional context that the name machine_user_countdown doesn't already give me. If we want to write helpful docs then we should answer questions like "what is a machine user" maybe what units is the countdown in etc. As it stands it feels a bit like this is documenting things just for the sake of saying we have docs.

[DominicOram]

Nit: I always thought having these as arguments was kind of silly. When would we ever change them?

[Villtord]

We probably will never change them, but if someone wants to reuse our code in a different synchrotron they would need it. Not that it is difficult to add though... That's the only reasoning I see behind it. But I get a feeling that we don't have such purpose of having this repo reused. Or do we?

[Villtord]

Thanks, I'm not a massive fan of docs like these. Like Read-only signal for the machine user countdown timer. gives me no additional context that the name machine_user_countdown doesn't already give me. If we want to write helpful docs then we should answer questions like "what is a machine user" maybe what units is the countdown in etc. As it stands it feels a bit like this is documenting things just for the sake of saying we have docs.

I was more thinking of having more useful help() that gives list of Args and Attributes available.

[fajinyuan]

What is the recommended or agreed pydoc style in Diamond II developments? sphinx, google stype, numpy, or pydoc? do we need to support cross-reference in the doc string or not?

[Villtord]

What is the recommended or agreed pydoc style in Diamond II developments? sphinx, google stype, numpy, or pydoc? do we need to support cross-reference in the doc string or not?

Google style with few exceptions according to https://diamondlightsource.github.io/dodal/main/reference/style-guide.html