Add 0.10 docs #700

coretl · 2024-12-09T16:50:42Z

Initially just an outline of what I will write, in a couple of weeks this PR will have the actual docs in it

coretl · 2025-01-22T16:32:44Z

@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

Forks off of #700

evalott100 · 2025-01-30T12:10:06Z

Will continue tomorrow.

Observations

`TypeVar`s

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'

mrakitin requested a review from jennmald December 9, 2024 16:57

coretl force-pushed the docs branch from d5d5137 to 8ddce1e Compare December 17, 2024 09:14

coretl force-pushed the docs branch 4 times, most recently from a07bd8d to 05bad25 Compare January 13, 2025 16:57

coretl force-pushed the docs branch from 05bad25 to 2da89ea Compare January 17, 2025 16:46

coretl added 3 commits January 20, 2025 16:42

Rename ophyd_async.{epics,tango}.sim -> demo

ab4abd6

Fix typo in import linter

4bbcb0b

Rewrite sim and epics.demo devices to do the same

20b4aa7

coretl force-pushed the docs branch from 2da89ea to 4ea18ef Compare January 20, 2025 16:43

coretl changed the title ~~Add 1.0 docs~~ Add 0.10 docs Jan 20, 2025

coretl force-pushed the docs branch 2 times, most recently from 73cc77e to f68f00c Compare January 21, 2025 16:54

WIP

9563aee

coretl force-pushed the docs branch from f68f00c to 9563aee Compare January 22, 2025 15:51

Merge remote-tracking branch 'origin/main' into docs

f8df64c

evalott100 added a commit that referenced this pull request Jan 28, 2025

WIP: docs with TypeVar in private modules

4a5ca3b

Forks off of #700

coretl and others added 5 commits January 29, 2025 09:11

Fix SignalDatatypeT docs

9045e03

Localise usage of T to each module

e5e9df0

Add docstrings without breaking type checking

e2faf90

Add some more docs

6415270

WIP: added docstrings

bbe4ffa

coretl added 5 commits January 30, 2025 15:39

Tidy ADAravis and write how-to areaDetector

021790c

Localise use of T in tests

f44961e

Fix tests

43dae53

Merge branch 'docs' of github.com:bluesky/ophyd-async into docs

872bd54

Merge remote-tracking branch 'origin/main' into docs

c702f2e

coretl mentioned this pull request Jan 31, 2025

Update all the detectors and ADCore to match ADAravis #754

Open

coretl added 5 commits January 31, 2025 09:56

Another attempt at fixing tests

2f6b553

Fix tests and add prints

606ca19

Try to shorten tutorials

3d4fe17

Patch out more plotting

10a0de2

Fix tests on windows

e548c74

evalott100 force-pushed the docs branch from e548c74 to fc2291c Compare January 31, 2025 11:53

coretl and others added 5 commits January 31, 2025 11:56

Merge branch 'docs' of github.com:bluesky/ophyd-async into docs

4d60dc4

Merge remote-tracking branch 'origin/main' into docs

4060f98

Another attempt at fixing tests

ba70759

Fix tests and add prints

da625bf

WIP

c403761

evalott100 force-pushed the docs branch from fc2291c to c403761 Compare January 31, 2025 11:57

coretl and others added 5 commits January 31, 2025 13:15

Merge remote-tracking branch 'origin/docs' into docs

4a91d7f

WIP: more docstrings

fa017f0

Add another article

65831b6

Merge branch 'docs' of github.com:bluesky/ophyd-async into docs

c7230ac

More docstrings

ca0ff7f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add 0.10 docs #700

Add 0.10 docs #700

coretl commented Dec 9, 2024 •

edited

Loading

coretl commented Jan 22, 2025

evalott100 commented Jan 30, 2025 •

edited

Loading

Add 0.10 docs #700

Are you sure you want to change the base?

Add 0.10 docs #700

Conversation

coretl commented Dec 9, 2024 • edited Loading

coretl commented Jan 22, 2025

evalott100 commented Jan 30, 2025 • edited Loading

Observations

TypeVars

Event model types

TriggerInfo

DeviceProcessor

Numpy types

Asyncio types

Table

AD Core stuff

Unused InvalidFlyMotorException

Tango

Myst cross-reference issues

coretl commented Dec 9, 2024 •

edited

Loading

evalott100 commented Jan 30, 2025 •

edited

Loading

`TypeVar`s

Unused `InvalidFlyMotorException`