From 62e9d01b5eb33e367d0fc5ea3855c973872bcd85 Mon Sep 17 00:00:00 2001 From: "Ware, Joseph (DLSLtd,RAL,LSCI)" Date: Wed, 17 Apr 2024 11:25:37 +0100 Subject: [PATCH] Replace api.md with api.rst to ensure autodoc generation --- docs/_templates/custom-class-template.rst | 1 + docs/conf.py | 4 +++- docs/how-to/make-a-simple-device.rst | 14 +++++------ docs/how-to/write-tests-for-devices.rst | 2 +- docs/reference/api.md | 17 ------------- docs/reference/api.rst | 29 +++++++++++++++++++++++ docs/tutorials/using-existing-devices.rst | 16 ++++++------- 7 files changed, 49 insertions(+), 34 deletions(-) delete mode 100644 docs/reference/api.md create mode 100644 docs/reference/api.rst diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst index 1be188ca53..236b77063c 100644 --- a/docs/_templates/custom-class-template.rst +++ b/docs/_templates/custom-class-template.rst @@ -9,6 +9,7 @@ .. autoclass:: {{ objname }} :members: + :undoc-members: :show-inheritance: :inherited-members: :special-members: __call__, __add__, __mul__ diff --git a/docs/conf.py b/docs/conf.py index 312f26070a..8c66c9e8c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,13 +62,14 @@ # If true, Sphinx will warn about all references where the target cannot # be found. -nitpicky = True +# nitpicky = True # A list of (type, target) tuples (by default empty) that should be ignored when # generating warnings in "nitpicky mode". Note that type should include the # domain name if present. Example entries would be ('py:func', 'int') or # ('envvar', 'LD_LIBRARY_PATH'). nitpick_ignore = [ + # builtins ("py:class", "NoneType"), ("py:class", "'str'"), ("py:class", "'float'"), @@ -76,6 +77,7 @@ ("py:class", "'bool'"), ("py:class", "'object'"), ("py:class", "'id'"), + # typing ("py:class", "typing_extensions.Literal"), ] diff --git a/docs/how-to/make-a-simple-device.rst b/docs/how-to/make-a-simple-device.rst index 204cd1df6e..1ed354381a 100644 --- a/docs/how-to/make-a-simple-device.rst +++ b/docs/how-to/make-a-simple-device.rst @@ -9,16 +9,16 @@ Make a Simple Device .. currentmodule:: ophyd_async.core To make a simple device, you need to subclass from the -:class:`StandardReadable` class, create some :class:`Signal` instances, and optionally implement +`StandardReadable` class, create some `Signal` instances, and optionally implement other suitable Bluesky `Protocols ` like -:class:`~bluesky.protocols.Movable`. +`~bluesky.protocols.Movable`. The rest of this guide will show examples from ``src/ophyd_async/epics/demo/__init__.py`` Readable -------- -For a simple :class:`~bluesky.protocols.Readable` object like a :class:`Sensor`, you need to +For a simple `~bluesky.protocols.Readable` object like a `Sensor`, you need to define some signals, then tell the superclass which signals should contribute to ``read()`` and ``read_configuration()``: @@ -34,7 +34,7 @@ its Python type, which could be: The rest of the arguments are PV connection information, in this case the PV suffix. -Finally :class:`super().__init__() ` is called with: +Finally `super().__init__() ` is called with: - Possibly empty Device ``name``: will also dash-prefix its child Device names is set - Optional ``primary`` signal: a Signal that should be renamed to take the name @@ -50,18 +50,18 @@ and ``unstage()`` and their cached values returned on ``read()`` and Movable ------- -For a more complicated device like a :class:`Mover`, you can still use :class:`StandardReadable` +For a more complicated device like a `Mover`, you can still use `StandardReadable` and implement some addition protocols: .. literalinclude:: ../../src/ophyd_async/epics/demo/__init__.py :pyobject: Mover -The ``set()`` method implements :class:`~bluesky.protocols.Movable`. This +The ``set()`` method implements `~bluesky.protocols.Movable`. This creates a `coroutine` ``do_set()`` which gets the old position, units and precision in parallel, sets the setpoint, then observes the readback value, informing watchers of the progress. When it gets to the requested value it completes. This co-routine is wrapped in a timeout handler, and passed to an -:class:`AsyncStatus` which will start executing it as soon as the Run Engine adds a +`AsyncStatus` which will start executing it as soon as the Run Engine adds a callback to it. The ``stop()`` method then pokes a PV if the move needs to be interrupted. diff --git a/docs/how-to/write-tests-for-devices.rst b/docs/how-to/write-tests-for-devices.rst index 9c8602220b..c1e5ca1c43 100644 --- a/docs/how-to/write-tests-for-devices.rst +++ b/docs/how-to/write-tests-for-devices.rst @@ -24,7 +24,7 @@ Async Tests Sim Backend ----------- -Ophyd devices initialized with a sim backend behave in a similar way to mocks, without requiring you to mock out all the dependencies and internals. The :class:`DeviceCollector` can initialize any number of devices, and their signals and sub-devices (recursively), with a sim backend. +Ophyd devices initialized with a sim backend behave in a similar way to mocks, without requiring you to mock out all the dependencies and internals. The `DeviceCollector` can initialize any number of devices, and their signals and sub-devices (recursively), with a sim backend. .. literalinclude:: ../../tests/epics/demo/test_demo.py :pyobject: sim_sensor diff --git a/docs/reference/api.md b/docs/reference/api.md deleted file mode 100644 index 13d1ca5a65..0000000000 --- a/docs/reference/api.md +++ /dev/null @@ -1,17 +0,0 @@ -# API - -```{eval-rst} -.. automodule:: ophyd_async - - ``ophyd_async`` - ----------------------------------- -``` - -This is the internal API reference for ophyd_async - -```{eval-rst} -.. data:: ophyd_async.__version__ - :type: str - - Version number as calculated by https://github.com/pypa/setuptools_scm -``` diff --git a/docs/reference/api.rst b/docs/reference/api.rst new file mode 100644 index 0000000000..66747af774 --- /dev/null +++ b/docs/reference/api.rst @@ -0,0 +1,29 @@ +.. note:: + + Ophyd async is included on a provisional basis until the v1.0 release and + may change API on minor release numbers before then + +API +=== + +.. automodule:: ophyd_async + + ``ophyd_async`` + ----------------------------------- + +This is the internal API reference for ophyd_async + +.. data:: ophyd_async.__version__ + :type: str + + Version number as calculated by https://github.com/pypa/setuptools_scm + + +.. autosummary:: + :toctree: ../generated + :template: custom-module-template.rst + :recursive: + + core + epics + panda \ No newline at end of file diff --git a/docs/tutorials/using-existing-devices.rst b/docs/tutorials/using-existing-devices.rst index 5c096b7306..a0ebf9a591 100644 --- a/docs/tutorials/using-existing-devices.rst +++ b/docs/tutorials/using-existing-devices.rst @@ -41,20 +41,20 @@ 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 :module:`epics.demo` module: +Finally we create the Ophyd Async devices imported from the `epics.demo` module: .. literalinclude:: ../examples/epics_demo.py :language: python :start-after: # Create ophyd-async devices -The first thing to note is `with`. This uses a :class:`DeviceCollector` as a context -manager to collect up the top level :class:`Device` instances created in the context, +The first thing to note is `with`. This uses a `DeviceCollector` as a context +manager to collect up the top level `Device` instances created in the context, and run the following: -- If ``set_name=True`` (the default), then call :meth:`Device.set_name` passing the +- If ``set_name=True`` (the default), then call `Device.set_name` passing the name of the variable within the context. For example, here we call ``det.set_name("det")`` -- If ``connect=True`` (the default), then call :meth:`Device.connect` in parallel for +- If ``connect=True`` (the default), then call `Device.connect` in parallel for all top level Devices, waiting for up to ``timeout`` seconds. For example, here we call ``asyncio.wait([det.connect(), samp.connect()])`` - If ``sim=True`` is passed, then don't connect to PVs, but set Devices into @@ -134,7 +134,7 @@ We can do a relative move of ``samp.x`` by 10mm, using `bluesky.plan_stubs.mvr`: In [1]: