Fix docs CI job

.github/workflows/docs.yml

@@ -46,7 +46,7 @@ jobs:
         if: github.event_name == 'push' && github.actor != 'dependabot[bot]'
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: peaceiris/actions-gh-pages@64b46b4226a4a12da2239ba3ea5aa73e3163c75b # v3.9.1
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: .github/pages

.gitignore

@@ -84,4 +84,4 @@ docs/*/generated
 docs/savefig
 
 # generated version number
-ophyd/_version.py
+ophyd_async/_version.py

docs/conf.py

@@ -4,6 +4,7 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
 import sys
 from pathlib import Path
 from subprocess import check_output
@@ -13,6 +14,8 @@
 import ophyd_async
 
 # -- General configuration ------------------------------------------------
+# Source code dir relative to this file
+sys.path.insert(0, os.path.abspath("../../src"))
 
 # General information about the project.
 project = "ophyd_async"
@@ -208,14 +211,17 @@
 # every member listed in __all__ and no others. Default is True
 autosummary_ignore_module_all = False
 
+# Turn on sphinx.ext.autosummary
+autosummary_generate = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # Look for signatures in the first line of the docstring (used for C functions)
 autodoc_docstring_signature = True
 
 # numpydoc config
 numpydoc_show_class_members = False
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # Where to put Ipython savefigs
 ipython_savefig_dir = "../build/savefig"

docs/developer/explanations/decisions/0004-repository-structure.rst

@@ -1,3 +1,9 @@
+.. role:: bash(code)
+   :language: bash
+
+.. role:: python(code)
+   :language: python
+
 4. Repository Structure
 =======================
 
@@ -91,10 +97,10 @@ During this process, the folder structure should incrementally be changed to
     │   └── epics
     └── ...
 
-The `__init__.py` files of each submodule (core, epics, panda and eventually tango) will
+The :bash:`__init__.py` files of each submodule (core, epics, panda and eventually tango) will
 be modified such that end users experience little disruption to how they use Ophyd Async.
-For such users, `from ophyd.v2.core import ...` can be replaced with 
-`from ophyd_async.core import ...`.
+For such users, :python:`from ophyd.v2.core import ...` can be replaced with 
+:python:`from ophyd_async.core import ...`.
 
 
 Consequences

docs/user/how-to/make-a-simple-device.rst

@@ -13,7 +13,7 @@ To make a simple device, you need to subclass from the
 other suitable Bluesky `Protocols <hardware_interface>` like
 :class:`~bluesky.protocols.Movable`.
 
-The rest of this guide will show examples from ``src/ophyd_async/core/epicsdemo/__init__.py``
+The rest of this guide will show examples from ``src/ophyd_async/epics/demo/__init__.py``
 
 Readable
 --------
@@ -22,7 +22,7 @@ For a simple :class:`~bluesky.protocols.Readable` object like a `Sensor`, you ne
 define some signals, then tell the superclass which signals should contribute to
 ``read()`` and ``read_configuration()``:
 
-.. literalinclude:: ../../../src/ophyd_async/core/epicsdemo/__init__.py
+.. literalinclude:: ../../../src/ophyd_async/epics/demo/__init__.py
    :pyobject: Sensor
 
 First some Signals are constructed and stored on the Device. Each one is passed
@@ -53,7 +53,7 @@ Movable
 For a more complicated device like a `Mover`, you can still use `StandardReadable`
 and implement some addition protocols:
 
-.. literalinclude:: ../../../src/ophyd_async/core/epicsdemo/__init__.py
+.. literalinclude:: ../../../src/ophyd_async/epics/demo/__init__.py
    :pyobject: Mover
 
 The ``set()`` method implements :class:`~bluesky.protocols.Movable`. This
@@ -70,7 +70,7 @@ Assembly
 
 Compound assemblies can be used to group Devices into larger logical Devices:
 
-.. literalinclude:: ../../../src/ophyd_async/core/epicsdemo/__init__.py
+.. literalinclude:: ../../../src/ophyd_async/epics/demo/__init__.py
    :pyobject: SampleStage
 
 This applies prefixes on construction:

docs/user/reference/api.rst

@@ -6,9 +6,9 @@
 API
 ===
 
-.. automodule:: ophyd_async.core
+.. automodule:: ophyd_async
 
-    ``ophyd_async.core``
+    ``ophyd_async``
     -----------------------------------
 
 This is the internal API reference for ophyd_async
@@ -24,12 +24,6 @@ This is the internal API reference for ophyd_async
     :template: custom-module-template.rst
     :recursive:
 
-    ophyd_async.core._device
-    ophyd_async.core.async_status
-    ophyd_async.core.utils
-    ophyd_async.epics.areadetector
-    ophyd_async.epics.demo
-    ophyd_async.epics.motion
-    ophyd_async.epics.signal
-    ophyd_async.epics._backend
-    ophyd_async.panda
+    core
+    epics
+    panda

docs/user/tutorials/using-existing-devices.rst

@@ -41,7 +41,7 @@ that you can mix Ophyd and Ophyd Async devices in the same RunEngine:
     :start-after: # Create ophyd devices
     :end-before: # Create ophyd-async devices
 
-Finally we create the Ophyd Async devices imported from the `epicsdemo` module:
+Finally we create the Ophyd Async devices imported from the `epics.demo` module:
 
 .. literalinclude:: ../examples/epics_demo.py
     :language: python
@@ -171,4 +171,4 @@ device we can see it gives the same result:
 
 .. seealso::
 
-    How-to `../how-to/make-a-simple-device` to make your own Ophyd Async devices.
+    How-to `../how-to/make-a-simple-device` to make your own Ophyd Async devices.

src/ophyd_async/core/_device/standard_readable.py

@@ -30,11 +30,11 @@ def set_readable_signals(
         Parameters
         ----------
         read:
-            Signals to make up `read()`
+            Signals to make up :meth:`~StandardReadable.read`
         conf:
-            Signals to make up `read_configuration()`
+            Signals to make up :meth:`~StandardReadable.read_configuration`
         read_uncached:
-            Signals to make up `read()` that won't be cached
+            Signals to make up :meth:`~StandardReadable.read` that won't be cached
         """
         self._read_signals = tuple(read)
         self._configuration_signals = tuple(config)

src/ophyd_async/epics/signal/pvi_get.py

@@ -1,6 +1,6 @@
 from typing import Dict, TypedDict
 
-from p4p.client.thread import Context
+from p4p.client.asyncio import Context
 
 
 class PVIEntry(TypedDict, total=False):

tests/conftest.py

@@ -86,18 +86,3 @@ async def inner_coroutine():
         raise ValueError()
 
     return inner_coroutine
-
-
-class DocHolder:
-    def __init__(self):
-        self.names = []
-        self.docs = []
-
-    def append(self, name, doc):
-        self.names.append(name)
-        self.docs.append(doc)
-
-
-@pytest.fixture
-def doc_holder() -> DocHolder:
-    return DocHolder()

tests/epics/areadetector/test_hdf_streamer_det.py

@@ -18,6 +18,21 @@
 )
 
 
+class DocHolder:
+    def __init__(self):
+        self.names = []
+        self.docs = []
+
+    def append(self, name, doc):
+        self.names.append(name)
+        self.docs.append(doc)
+
+
+@pytest.fixture
+def doc_holder():
+    return DocHolder()
+
+
 @pytest.fixture
 async def hdf_streamer_dets():
     dp = TmpDirectoryProvider()
@@ -51,9 +66,9 @@ async def hdf_streamer_dets():
 
 
 async def test_hdf_streamer_dets_step(
-    hdf_streamer_dets: List[HDFStreamerDet], RE, doc_holder
+    hdf_streamer_dets: List[HDFStreamerDet], RE, doc_holder: DocHolder
 ):
-    RE(bp.count(hdf_streamer_dets), doc_holder.append)  # type: ignore
+    RE(bp.count(hdf_streamer_dets), doc_holder.append)
 
     drv = hdf_streamer_dets[0].drv
     assert 1 == await drv.acquire.get_value()
@@ -66,7 +81,7 @@ async def test_hdf_streamer_dets_step(
     assert 0 == await hdf.num_capture.get_value()
     assert FileWriteMode.stream == await hdf.file_write_mode.get_value()
 
-    assert doc_holder.names == [  # type: ignore
+    assert doc_holder.names == [
         "start",
         "descriptor",
         "stream_resource",
@@ -76,7 +91,7 @@ async def test_hdf_streamer_dets_step(
         "event",
         "stop",
     ]
-    _, descriptor, sra, sda, srb, sdb, event, _ = doc_holder.docs  # type: ignore
+    _, descriptor, sra, sda, srb, sdb, event, _ = doc_holder.docs
     assert descriptor["configuration"]["deta"]["data"]["deta-drv-acquire_time"] == 0.8
     assert descriptor["configuration"]["detb"]["data"]["detb-drv-acquire_time"] == 1.8
     assert descriptor["data_keys"]["deta"]["shape"] == [768, 1024]
@@ -94,7 +109,7 @@ async def test_hdf_streamer_dets_step(
 # TODO: write test where they are in the same stream after
 #   https://github.com/bluesky/bluesky/issues/1558
 async def test_hdf_streamer_dets_fly_different_streams(
-    hdf_streamer_dets: List[HDFStreamerDet], RE, doc_holder
+    hdf_streamer_dets: List[HDFStreamerDet], RE, doc_holder: DocHolder
 ):
     deta, detb = hdf_streamer_dets
 
@@ -121,10 +136,10 @@ def fly_det(num: int):
                 yield from bps.collect(det, stream=True, return_payload=False)
         yield from bps.wait(group="complete")
 
-    RE(fly_det(5), doc_holder.append)  # type: ignore
+    RE(fly_det(5), doc_holder.append)
 
     # TODO: stream_* will come after descriptor soon
-    assert doc_holder.names == [  # type: ignore
+    assert doc_holder.names == [
         "start",
         "stream_resource",
         "stream_datum",
@@ -146,7 +161,7 @@ def fly_det(num: int):
     assert 0 == await hdf.num_capture.get_value()
     assert FileWriteMode.stream == await hdf.file_write_mode.get_value()
 
-    _, sra, sda, descriptora, srb, sdb, descriptorb, _ = doc_holder.docs  # type: ignore
+    _, sra, sda, descriptora, srb, sdb, descriptorb, _ = doc_holder.docs
 
     assert descriptora["configuration"]["deta"]["data"]["deta-drv-acquire_time"] == 0.8
     assert descriptorb["configuration"]["detb"]["data"]["detb-drv-acquire_time"] == 1.8

tests/epics/areadetector/test_single_trigger_det.py

@@ -10,6 +10,21 @@
 )
 
 
+class DocHolder:
+    def __init__(self):
+        self.names = []
+        self.docs = []
+
+    def append(self, name, doc):
+        self.names.append(name)
+        self.docs.append(doc)
+
+
+@pytest.fixture
+def doc_holder():
+    return DocHolder()
+
+
 @pytest.fixture
 async def single_trigger_det():
     async with DeviceCollector(sim=True):
@@ -30,16 +45,18 @@ async def single_trigger_det():
     yield det
 
 
-async def test_single_trigger_det(single_trigger_det: SingleTriggerDet, RE, doc_holder):
-    RE(bp.count([single_trigger_det]), doc_holder.append)  # type: ignore
+async def test_single_trigger_det(
+    single_trigger_det: SingleTriggerDet, RE, doc_holder: DocHolder
+):
+    RE(bp.count([single_trigger_det]), doc_holder.append)
 
     drv = single_trigger_det.drv
     assert 1 == await drv.acquire.get_value()
     assert ImageMode.single == await drv.image_mode.get_value()
     assert True is await drv.wait_for_plugins.get_value()
 
-    assert doc_holder.names == ["start", "descriptor", "event", "stop"]  # type: ignore
-    _, descriptor, event, _ = doc_holder.docs  # type: ignore
+    assert doc_holder.names == ["start", "descriptor", "event", "stop"]
+    _, descriptor, event, _ = doc_holder.docs
     assert descriptor["configuration"]["det"]["data"]["det-drv-acquire_time"] == 0.5
     assert (
         descriptor["data_keys"]["det-stats-unique_id"]["source"]