Replace api.md with api.rst to ensure autodoc generation

docs/_templates/custom-class-template.rst

@@ -9,6 +9,7 @@
 
 .. autoclass:: {{ objname }}
    :members:
+   :undoc-members:
    :show-inheritance:
    :inherited-members:
    :special-members: __call__, __add__, __mul__

docs/conf.py

@@ -62,20 +62,22 @@
 
 # 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'"),
     ("py:class", "'int'"),
     ("py:class", "'bool'"),
     ("py:class", "'object'"),
     ("py:class", "'id'"),
+    # typing
     ("py:class", "typing_extensions.Literal"),
 ]
 

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 <hardware_interface>` 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__() <StandardReadable>` is called with:
+Finally `super().__init__() <StandardReadable>` 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. 
 

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

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

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]: <movr(samp.x, -10)
 
 Individual Devices will also expose some of the parameters of the underlying
-hardware on itself. In the case of a :class:`Mover`, we can set and get its
+hardware on itself. In the case of a `Mover`, we can set and get its
 ``velocity``:
 
 .. ipython::
@@ -161,8 +161,8 @@ There is also an "energy mode" that can be changed to modify the ``det`` output.
 
     In [1]: <rd(det.mode)
 
-Although this is an :class:`~enum.Enum` and programmatic code should import and
-use instances of :class:`EnergyMode`, we can set it using a
+Although this is an `~enum.Enum` and programmatic code should import and
+use instances of `EnergyMode`, we can set it using a
 string value on the commandline:
 
 .. ipython::