Merge pull request #105 from ISISComputingGroup/78-docs-make-classfunction-names-link-through-to-api-reference-more-consistently

78 docs make classfunction names link through to api reference more consistently

Author: jackbdoughty

doc/callbacks/docs_logging_callback.md

@@ -1,5 +1,5 @@
 # Document Logging Callback
 
-The document logger is a callback that the BlueSky RunEngine subscribes to unconditionally. After receiving each document, if they share the same start document (in the same run) then it will write them to the same file. These logs are stored under `C:/instrument/var/logs/bluesky/raw_documents` and are handled by the log rotation.
+The [`document_logger`](ibex_bluesky_core.callbacks.document_logger) is a callback that the BlueSky RunEngine subscribes to unconditionally. After receiving each document, if they share the same start document (in the same run) then it will write them to the same file. These logs are stored under `C:/instrument/var/logs/bluesky/raw_documents` and are handled by the log rotation.
 
 Each document is stored in a JSON format so can be both machine and human readable. It is in the format `{"type": name, "document": document}` whereby `name` is the type of the document, e.g start, stop, event, descriptor and the `document` is the [document from BlueSky in JSON format](https://blueskyproject.io/bluesky/main/documents.html). As these files are produced per BlueSky run, these will be useful for debugging.

doc/callbacks/file_writing.md

@@ -1,7 +1,7 @@
 # File writing callbacks
 ## Human readable files
 
-A callback (`HumanReadableFileCallback`) exists to write all documents to a separate human-readable file which contains the specified fields. 
+A callback ([`HumanReadableFileCallback`](ibex_bluesky_core.callbacks.file_logger.HumanReadableFileCallback))  exists to write all documents to a separate human-readable file which contains the specified fields. 
 
 This callback will add units and honour precision for each field as well as add some metadata ie. the `uid` of each scan as well as the RB number, which is injected using the {doc}`/preprocessors/rbnumberpp`
 

doc/callbacks/plotting.md

@@ -1,26 +1,26 @@
 # Plotting
 
 Bluesky has good integration with `matplotlib` for data visualization, and data from scans 
-may be easily plotted using the `LivePlot` callback.
+may be easily plotted using the [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot)  callback.
 
 `ibex_bluesky_core` provides a thin wrapper over bluesky's default `LivePlot` callback,
 which ensures that plots are promptly displayed in IBEX.
 
-In order to use the wrapper, import `LivePlot` from `ibex_bluesky_core` rather than 
+In order to use the wrapper, import [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot) from [`ibex_bluesky_core`](ibex_bluesky_core) rather than 
 `bluesky` directly:
 ```
 from ibex_bluesky_core.callbacks.plotting import LivePlot
 ```
 
 ## Configuration
 
-A range of configuration options for `LivePlot` are available - see the 
+A range of configuration options for [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot) are available - see the 
 [bluesky `LivePlot` documentation](https://blueskyproject.io/bluesky/main/callbacks.html#bluesky.callbacks.mpl_plotting.LivePlot)
 for more details about available options.
 
-The `LivePlot` object allows an arbitrary set of matplotlib `Axes` to be passed in, onto
+The [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot) object allows an arbitrary set of matplotlib `Axes` to be passed in, onto
 which it will plot. This can be used to configure properties which are not directly exposed 
-on the `LivePlot` object, for example log-scaled axes.
+on the [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot) object, for example log-scaled axes.
 
 See the [matplotlib `Axes` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html) 
 for a full range of options on how to configure an `Axes` object.
@@ -50,7 +50,7 @@ See [docs for `call_qt_aware`](../plan_stubs/matplotlib_helpers.md) for a descri
 `yield from call_qt_aware` rather than calling `matplotlib` functions directly.
 ```
 
-By providing a signal name to the `yerr` argument you can pass uncertainties to LivePlot, by not providing anything for this argument means that no errorbars will be drawn. Errorbars are drawn after each point collected, displaying their standard deviation- uncertainty data is collected from Bluesky event documents and errorbars are updated after every new point added.
+By providing a signal name to the `yerr` argument you can pass uncertainties to [`LivePlot`](ibex_bluesky_core.callbacks.plotting.LivePlot), by not providing anything for this argument means that no errorbars will be drawn. Errorbars are drawn after each point collected, displaying their standard deviation- uncertainty data is collected from Bluesky event documents and errorbars are updated after every new point added.
 
 The `plot_callback` object can then be subscribed to the run engine, using either:
 - An explicit callback when calling the run engine: `RE(some_plan(), plot_callback)`

doc/dev/logging.md

@@ -1,5 +1,5 @@
 # Logging
-To invoke the `ibex_bluesky_core` logger, create and use a `logger` object in [the standard way](https://docs.python.org/3/library/logging.html):
+To invoke the [`ibex_bluesky_core`](ibex_bluesky_core) logger, create and use a `logger` object in [the standard way](https://docs.python.org/3/library/logging.html):
 
 ```python
 import logging

doc/devices/blocks.md

@@ -3,7 +3,7 @@
 Blocks are one of IBEX's central abstractions, which present a uniform interface to any
 scientifically interesting PV.
 
-`ibex_bluesky_core` has support for four types of blocks:
+[`ibex_bluesky_core`](ibex_bluesky_core) has support for four types of blocks:
 - Read-only
 - Read/write
 - Read/write with setpoint readback
@@ -25,7 +25,7 @@ mot: NotConnected:
 
 ## Block types
 
-### `block_r` (read-only)
+### [`block_r`](ibex_bluesky_core.devices.block.block_r) (read-only)
 
 This is a read-only block. It supports `bluesky`'s `Readable` protocol, as well as
 basic metadata protocols such as `HasName`.
@@ -35,20 +35,20 @@ This type of block is usable by:
 - Plan stubs like `bluesky.plan_stubs.rd()`, which plans may use to get the current value
 of a block easily for use in the plan.
 
-A `BlockR` object does not implement any logic on read - it simply returns the most recent
+A [`BlockR`](ibex_bluesky_core.devices.block.BlockR) object does not implement any logic on read - it simply returns the most recent
 value of the block.
 
-A simple constructor, `block_r`, is available, which assumes the current instrument's PV
+A simple constructor, [`block_r`](ibex_bluesky_core.devices.block.block_r), is available, which assumes the current instrument's PV
 prefix:
 
 ```python
 from ibex_bluesky_core.devices.block import block_r
 readable_block = block_r(float, "my_block_name")
 ```
 
-### `block_rw` (read, write)
+### [`block_rw`](ibex_bluesky_core.devices.block.block_rw)  (read, write)
 
-This is a read-write block. It supports all of the same protocols as `BlockR`, with the
+This is a read-write block. It supports all of the same protocols as [`BlockR`](ibex_bluesky_core.devices.block.BlockR), with the
 addition of the `Movable` protocol.
 
 The addition of the movable protocol means that this type of block can be moved by plan 
@@ -65,7 +65,7 @@ It can also be used as the `Movable` in full plans like `bluesky.plans.scan()`.
  are not motors, even if the documentation tends to use motors as the examples.
 ```
 
-Like `block_r`, a simple constructor is available:
+Like [`block_r`](ibex_bluesky_core.devices.block.block_r), a simple constructor is available:
 
 ```python
 from ibex_bluesky_core.devices.block import block_rw, BlockWriteConfig
@@ -79,9 +79,9 @@ writable_block = block_rw(
 ```
 
 
-### `block_rw_rbv` (read, write, setpoint readback)
+### [`block_rw_rbv`](ibex_bluesky_core.devices.block.block_rw_rbv) (read, write, setpoint readback)
 
-This is a block with full support for reading and writing as per `BlockRw`, but with
+This is a block with full support for reading and writing as per [`BlockRw`](ibex_bluesky_core.devices.block.BlockRw), but with
 the addition of `bluesky`'s `Locatable` protocol, which allows you to read back the
 current setpoint. Where possible, the setpoint will be read back from hardware.
 
@@ -91,7 +91,7 @@ This object is also more suitable for use in plans which use relative moves - th
 relative move will be calculated with respect to the setpoint readback from hardware
 (if available).
 
-Just like `block_rw`, a simple constructor is available:
+Just like [`block_rw`](ibex_bluesky_core.devices.block.block_rw), a simple constructor is available:
 
 ```python
 from ibex_bluesky_core.devices.block import block_rw_rbv, BlockWriteConfig
@@ -104,7 +104,7 @@ rw_rbv_block = block_rw_rbv(
 )
 ```
 
-### `block_mot` (motor-specific)
+### [`block_mot`](ibex_bluesky_core.devices.block.block_mot) (motor-specific)
 
 This represents a block pointing at a motor record. This has support for:
 - Reading (`Readable`)
@@ -123,7 +123,7 @@ the plan is executed against hardware.
 `Stoppable` means that the motor can be asked to stop by bluesky. Plans may choose to execute
 a `stop()` on failure, or explicitly during a plan.
 
-A `block_mot` can be made in a similar way to the other block types; however, it does not
+A [`block_mot`](ibex_bluesky_core.devices.block.block_mot) can be made in a similar way to the other block types; however, it does not
 require an explicit type as motors are always of `float` data type:
 
 ```python
@@ -132,20 +132,20 @@ mot_block = block_mot("motor_block")
 ```
 
 A motor block does not need an explicit write config: it always waits for the requested motion
-to complete. See {py:obj}`ibex_bluesky_core.devices.block.BlockMot` for a detailed mapping of
+to complete. See [`BlockMot`](ibex_bluesky_core.devices.block.BlockMot) for a detailed mapping of
 the usual write-configuration options and how these are instead achieved by a motor block.
 
 ## Configuring block write behaviour
 
-`BlockRw` and `BlockRwRbv` both take a `write_config` argument, which can be used to configure
+[`BlockRw`](ibex_bluesky_core.devices.block.BlockRw)  and [`BlockRwRbv`](ibex_bluesky_core.devices.block.BlockRwRbv)  both take a `write_config` argument, which can be used to configure
 the behaviour on writing to a block, for example tolerances and settle times.
 
-See {py:class}`ibex_bluesky_core.devices.block.BlockWriteConfig` for a detailed
+See [`BlockWriteConfig`](ibex_bluesky_core.devices.block.BlockWriteConfig) for a detailed
 description of all the options which are available.
 
-## Run control
+## Run Control
 
-Run control information is available via the `block.run_control` sub-device.
+[`RunControl`](ibex_bluesky_core.devices.block.RunControl) information is available via the [`block.RunControl`](ibex_bluesky_core.devices.block.RunControl) sub-device.
 
 Both configuring and reading the current status of run control are permitted.