Add 0.10 docs

[coretl]

Rewrite of the documentation and its structure including:

• Making sim and epics.demo devices do the same
• Placeholder for the same for tango.demo and fastcs.demo devices
• New tutorials, how-tos and explanations
• Reduce installed dependencies

The first half of #721
Fixes #677
Fixes #671
Fixes #484
Fixes #480
Fixes #479
Fixes #459
Fixes #443 (well enough anyway)
Fixes #386
Fixes #349
Fixes #303
Fixes #246
Fixes #227
Fixes #193
Fixes #622

[coretl]

@evalott100 please can you make a new branch off this one, then PR back to the docs branch fixing some of the warnings in https://github.com/bluesky/ophyd-async/actions/runs/12911955696/job/36005625932?

Some of them are just missing docstrings, but there are a bunch that say something like:

docstring of ophyd_async.core._signal.set_and_wait_for_value:1: WARNING: py:class reference target not found: ophyd_async.core._signal_backend.SignalDatatypeT

I think this is because importing ophyd_async.core._signal_backend.SignalDatatypeT into ophyd_async.core loses its doc-comment (doc-comment because it is a TypeVar not a class). I have no idea how to get sphinx to recognise that SignalDatatypeT exists and is of a particular type.

I have tried:

• Adding the following to ophyd_async.core.__init__:

"""
.. data:: SignalDatatypeT

    The supported `Signal` datatypes
"""

• Doing the same with .. class:: SignalDatatypeT
• Doing the same but in ophyd_async.core._signal_backend
• Peppering the codebase with from __future__ import annotations

My next steps were going to be:

• Add from __future__ import annotations for everything (don't know if you can do this for the whole module)
• Use autodoc_type_aliases to map ophyd_async.core._signal_backend.SignalDatatypeT to ophyd_async.core.SignalDatatypeT as defined by one of the methods above
• Do some googling

[evalott100]

Will continue tomorrow.

Observations

TypeVars

All broken throughout.

Event model types

It can't reference DataKey in the type hint despite event model being in the intersphinx mapping.

/home/eva/Code/ophyd-async/src/ophyd_async/core/__init__.py:docstring of ophyd_async.core._signal_backend.make_datakey:1: WARNING: 'any' reference target not found: DataKey

TriggerInfo

Can't get pydantic fields working so get the errors

...
/home/eva/Code/ophyd-async/src/ophyd_async/core/_detector.py:docstring of ophyd_async.core._detector.TriggerInfo:1: WARNING: py:obj reference target not found: ophyd_async.core._detector.TriggerInfo.livetime
/home/eva/Code/ophyd-async/src/ophyd_async/core/_detector.py:docstring of ophyd_async.core._detector.TriggerInfo:1: WARNING: py:obj reference target not found: ophyd_async.core._detector.TriggerInfo.frame_timeout
...

DeviceProcessor

/home/eva/Code/ophyd-async/src/ophyd_async/core/__init__.py:docstring of ophyd_async.core._device.init_devices:1: WARNING: py:class reference target not found: ophyd_async.core._device.DeviceProcessor

Sphinx can't find this, not in public api.

Numpy types

Related to TypeVar issues I think. But it's giving this issue on DeviceFiller, no idea why.

...
/home/eva/Code/ophyd-async/src/ophyd_async/core/_device_filler.py:docstring of ophyd_async.core._device_filler.DeviceFiller:1: WARNING: py:class reference target not found: numpy.int8
...

Asyncio types

Can't find asyncio.Task in async status...

/home/eva/Code/ophyd-async/src/ophyd_async/core/_status.py:docstring of ophyd_async.core._status.AsyncStatus:1: WARNING: py:class reference target not found: _asyncio.Task

We should be getting this through the python intersphinx mapping already present. I assume it's because of AS and WAS TypeVar weirdness.

Table

I think this is because of pydantic weirdness in the case of Table.all, and also decorators in the case of validate_array_dtypes.

/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.validate_array_dtypes
/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.all fields
/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.validate_lengths
/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.all fields
/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table.validate_array_dtypes:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.all fields
/home/eva/Code/ophyd-async/src/ophyd_async/core/_table.py:docstring of ophyd_async.core._table.Table.validate_lengths:1: WARNING: py:obj reference target not found: ophyd_async.core._table.Table.all fields

AD Core stuff

...
/scratch/twj43146/Programming/ophyd-async/src/ophyd_async/epics/adcore/_core_io.py:docstring of ophyd_async.epics.adcore._core_io.DetectorState:1:<autosummary>:1: WARNING: py:obj reference target not found: ophyd_async.epics.adcore.NDFileIO
...

To be covered in #754.

Unused InvalidFlyMotorException

`InvalidFlyMotorException`` is not actually used anywhere:

ophyd-async/src/ophyd_async/epics/motor.py

Lines 26 to 32 in 10a0de2

	class MotorLimitsException(Exception):
	pass
	class InvalidFlyMotorException(Exception):
	pass

Tango

Struggling with the DeviceProxy, AsyncDeviceProxy, and SyncDeviceProxy which define the __doc__ on a partial:

DeviceProxy = partial(get_device_proxy, green_mode=GreenMode.Asyncio)
DeviceProxy.__doc__ = """
    DeviceProxy(self, dev_name, wait=False, timeout=None)
        -> DeviceProxy
    ...
"""

scratch/twj43146/Programming/ophyd-async/src/ophyd_async/tango/core/__init__.py:docstring of ophyd_async.tango.core._signal.tango_signal_w:1: WARNING: py:class reference target not found: tango._tango.DeviceProxy
/scratch/twj43146/Programming/ophyd-async/src/ophyd_async/tango/core/__init__.py:docstring of ophyd_async.tango.core._signal.tango_signal_x:1: WARNING: py:class reference target not found: tango._tango.DeviceProxy
/scratch/twj43146/Programming/ophyd-async/src/ophyd_async/tango/core/_base_device.py:docstring of ophyd_async.tango.core._base_device.TangoDevice:1: WARNING: py:class reference target not found: tango._tango.DeviceProxy

Also having problems with DevVoid, and CommandInfo:

/scratch/twj43146/Programming/ophyd-async/src/ophyd_async/tango/demo/_tango/_servers.py:docstring of ophyd_async.tango.demo._tango._servers.DemoCounter.reset:1: WARNING: py:class reference target not found: DevVoid

/scratch/twj43146/Programming/ophyd-async/src/ophyd_async/tango/core/__init__.py:docstring of ophyd_async.tango.core._tango_transport.get_trl_descriptor:1: WARNING: py:class reference target not found: tango._tango.CommandInfo

Myst cross-reference issues

/scratch/twj43146/Programming/ophyd-async/docs/how-to/choose-right-baseclass.md:33: WARNING: 'myst' cross-reference target not found: 'TangoConnector'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/choose-right-baseclass.md:33: WARNING: 'myst' cross-reference target not found: 'EpicsConnector'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/choose-right-baseclass.md:33: WARNING: 'myst' cross-reference target not found: 'PviConnector'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/implement-ad-detector.md:16: WARNING: 'myst' cross-reference target not found: 'ADBaseIO'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/implement-ad-detector.md:25: WARNING: 'myst' cross-reference target not found: 'ADBaseController'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/implement-ad-detector.md:40: WARNING: 'myst' cross-reference target not found: 'ADWriter'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/implement-ad-detector.md:40: WARNING: 'myst' cross-reference target not found: 'adcore.ADHDFWriter'
/scratch/twj43146/Programming/ophyd-async/docs/how-to/implement-ad-detector.md:44: WARNING: 'myst' cross-reference target not found: 'adcore.NDPluginBase'
/scratch/twj43146/Programming/ophyd-async/docs/tutorials/implementing-devices.md:169: WARNING: 'myst' cross-reference target not found: 'SignalDatatype'

[coretl]

@evalott100 please could you give this another review?

I propose to merge this in approximately this state with further work in other tickets:

• Docstring format not decided yet: Decide on docstring format #755
• AreaDetector modules need to be more uniform: Update all the detectors and ADCore to match ADAravis #754
• observe_value docstring Document observe_value better #741
• load/save docs Write docs on load/save #758 and Document how to do stage and load as an analogy to ophyd's stage_sigs #674
• tutorial bootstrapping installs Update the tutorial docs to not rely on dev install #134

I will write up the last remaining tutorial (detectors) as part of another PR

[jwlodek]

Found a few typos

[evalott100]

Lots here, changes to the docs are great!

All the following should be regarded as NITs.

Addressed