Use abbreviations in more places

Author: Tom-Willemsen

doc/architectural_decisions/003-run-in-process.md

@@ -8,7 +8,7 @@ Current
 
 `bluesky` code can be run in several ways:
 - By the user at an interactive shell, directly calling the run engine in-process.
-- Underneath {py:obj}`run_plan()<ibex_bluesky_core.run_engine.run_plan>` if a plan/plan stub is to be run programmatically, which in turn calls the run engine. 
+- Underneath {py:obj}`~ibex_bluesky_core.run_engine.run_plan` if a plan/plan stub is to be run programmatically, which in turn calls the run engine. 
 - By a central worker process, to which the user would "submit" plans to run.
   - See DLS's `blueapi` for an example of a REST API for submitting plans to the run engine.
 

doc/architectural_decisions/007-output-file-archiving.md

@@ -7,12 +7,12 @@ Accepted
 ## Context
 
 Our bluesky implementation contains bluesky callbacks which produce scientist-facing output files, for example:
-- [Human-readable scan result files](/callbacks/file_writing): {py:obj}`HumanReadableFileCallback <ibex_bluesky_core.callbacks.HumanReadableFileCallback>`
-- [Fitting results](/callbacks/fitting/livefit_logger): {py:obj}`LiveFitLogger <ibex_bluesky_core.callbacks.LiveFitLogger>`
-- [Plot PNGs](#plot_png_saver): {py:obj}`PlotPNGSaver <ibex_bluesky_core.callbacks.PlotPNGSaver>`
+- [Human-readable scan result files](/callbacks/file_writing): {py:obj}`~ibex_bluesky_core.callbacks.HumanReadableFileCallback`
+- [Fitting results](/callbacks/fitting/livefit_logger): {py:obj}`~ibex_bluesky_core.callbacks.LiveFitLogger`
+- [Plot PNGs](#plot_png_saver): {py:obj}`~ibex_bluesky_core.callbacks.PlotPNGSaver`
 
 In addition, we have a {ref}`developer-facing callback for diagnostics <event_doc_cb>`, 
-{py:obj}`DocLoggingCallback <ibex_bluesky_core.callbacks.DocLoggingCallback>`.
+{py:obj}`~ibex_bluesky_core.callbacks.DocLoggingCallback`.
 
 The above callbacks produce files on disk in response to a bluesky scan. These files contain valuable data and so we
 need to consider how these files are archived for the long term. This must align with the 
@@ -268,7 +268,7 @@ unachievable - it would require too much work relative to using the existing `au
 
 At present, our scan file output format is explicitly designed to be "human-readable" (and, in fact, the callback which
 generates these files is explicitly called
-{py:obj}`HumanReadableFileCallback <ibex_bluesky_core.callbacks.HumanReadableFileCallback>`).
+{py:obj}`~ibex_bluesky_core.callbacks.HumanReadableFileCallback`).
 
 We have [issue 26](https://github.com/ISISComputingGroup/ibex_bluesky_core/issues/26) which will implement
 machine-readable files, using a format such as `.hdf5` or `.nxs`. These files will sit alongside the existing

doc/architectural_decisions/008-centre-of-mass.md

@@ -10,13 +10,13 @@ A decision needs to be made about whether to make changes to upstream Bluesky so
 
 ## Decision
 
-We will be making our own {py:obj}`CentreOfMass <ibex_bluesky_core.callbacks.CentreOfMass>` callback.
+We will be making our own {py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` callback.
 
 ## Justification & Consequences
 
 [We attempted to make changes to upstream Bluesky which were rejected](https://github.com/bluesky/bluesky/pull/1878), as it adds limits to the functionality of the callback. We also found other limitations with using their callback, such as not being able to have disordered and non-continuous data sent to it without it skewing the calculated value - we need it to work with disordered and non-continuous data as we need to be able to run continuous scans.
 
-We currently only need to support positive peaks, but in future a toggle could be added to {py:obj}`CentreOfMass <ibex_bluesky_core.callbacks.CentreOfMass>` to allow for negative peaks. 
+We currently only need to support positive peaks, but in future a toggle could be added to {py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` to allow for negative peaks. 
 
 This will mean that...
 - Our version of the callback will not be supported by Bluesky and may need changes as Bluesky updates.

doc/callbacks/centre_of_mass.md

@@ -6,7 +6,7 @@
 - `min(y)`
 - Straight-line segments joining `(x, y)` data points with their nearest neighbours along the x axis
 
-{py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` stores its result in the {py:obj}`result <ibex_bluesky_core.callbacks.CentreOfMass.result>` property.
+{py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` stores its result in the {py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass.result` property.
 
 :::{note}
 This will return **different** results from the `com` property available from {py:obj}`bluesky.callbacks.fitting.PeakStats` in the following cases:

doc/callbacks/fitting/fitting.md

@@ -1,4 +1,4 @@
-# Fitting (`LiveFit`)
+# Fitting ({py:obj}`~ibex_bluesky_core.callbacks.LiveFit`)
 
 Similar to [`LivePlot`](/callbacks/plotting.md), {py:obj}`ibex_bluesky_core.callbacks.LiveFit` provides a thin wrapper around Bluesky's {py:obj}`bluesky.callbacks.LiveFit` class, enhancing it with additional functionality to better support real-time data fitting. This wrapper not only offers a wide selection of models to fit your data on, but also introduces guess generation for fit parameters. As new data points are acquired, the wrapper refines these guesses dynamically, improving the accuracy of the fit with each additional piece of data, allowing for more efficient and adaptive real-time fitting workflows.
 
@@ -10,7 +10,7 @@ from ibex_bluesky_core.callbacks import LiveFit
 
 ## Configuration
 
-Below is a full example showing how to use standard {external+matplotlib:doc}`matplotlib <index>` & {external+bluesky:doc}`bluesky <index>` functionality to apply fitting to a scan, using {py:obj}`~ibex_bluesky_core.callbacks.LivePlot` and {py:obj}`~ibex_bluesky_core.callbacks.LiveFit`. The fitting callback is set to expect data to take the form of a Gaussian, using the {py:obj}`ibex_bluesky_core.fitting.Gaussian` model.
+Below is a full example showing how to use standard {external+matplotlib:doc}`matplotlib <index>` & {external+bluesky:doc}`bluesky <index>` functionality to apply fitting to a scan, using {py:obj}`~ibex_bluesky_core.callbacks.LivePlot` and {py:obj}`~ibex_bluesky_core.callbacks.LiveFit`. The fitting callback is set to expect data to take the form of a Gaussian, using the {py:obj}`~ibex_bluesky_core.fitting.Gaussian` model.
 
 ```python
 import matplotlib.pyplot as plt
@@ -78,7 +78,7 @@ Bluesky additionally provides a {py:obj}`bluesky.callbacks.fitting.PeakStats` ca
 
 -------
 
-Each of the above fit classes has a `.fit()` which returns an object of type {py:obj}`ibex_bluesky_core.fitting.FitMethod`. This tells {py:obj}`~ibex_bluesky_core.callbacks.LiveFit` how to perform fitting on the data.
+Each of the above fit classes has a `.fit()` which returns an object of type {py:obj}`~ibex_bluesky_core.fitting.FitMethod`. This tells {py:obj}`~ibex_bluesky_core.callbacks.LiveFit` how to perform fitting on the data.
 
 There are *two* ways that you can choose how to fit a model to your data:
 

doc/callbacks/isiscallbacks.md

@@ -28,13 +28,13 @@ Plotting is enabled by default and running a plan with {py:obj}`~ibex_bluesky_co
 
 If a {ref}`fitting method <standard_fitting_models>` is given via the `fit` argument (this is optional), fitting will be enabled. By default, this fit will be shown on a plot.
 
-After a scan has run you can get the fitting results by using the {py:obj}`live_fit <ibex_bluesky_core.callbacks.ISISCallbacks.live_fit>` property. 
+After a scan has run you can get the fitting results by using the {py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks.live_fit` property. 
 
 ## Centre of mass and Peak Stats
 
-These are both enabled by default. To access {py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` information after a plan, use the {py:obj}`com <ibex_bluesky_core.callbacks.ISISCallbacks.com>` property.
+These are both enabled by default. To access {py:obj}`~ibex_bluesky_core.callbacks.CentreOfMass` information after a plan, use the {py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks.com` property.
 
-To access {external+bluesky:py:obj}`Peak Stats <bluesky.callbacks.fitting.PeakStats>` after a plan use the {py:obj}`peak_stats <ibex_bluesky_core.callbacks.ISISCallbacks.peak_stats>` property.
+To access {external+bluesky:py:obj}`~bluesky.callbacks.fitting.PeakStats` after a plan, use the {py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks.peak_stats` property.
 
 ## File output
 

doc/dev/rbnumberpp.md

@@ -1,6 +1,6 @@
 # RB Number injection preprocessor
 
-A {external+bluesky:ref}`plan preprocessor <preprocessors>` exists for the run engine to inject the current RB number into all bluesky start documents. This is added to the run engine by default, but to remove this from the {py:obj}`bluesky.run_engine.RunEngine` use:
+A {external+bluesky:ref}`plan preprocessor <preprocessors>` exists for the run engine to inject the current RB number into all bluesky start documents. This is added to the run engine by default, but to remove this from the {py:obj}`~bluesky.run_engine.RunEngine`, use:
 
 ```python
 RE.preprocessors.pop()

doc/dev/troubleshooting.md

@@ -50,23 +50,23 @@ Scientist-facing output files are written to `<isis share>\inst$\NDX<inst>\user\
 default.
 
 Custom file-output paths can be specified by passing extra arguments to 
-{py:obj}`HumanReadableFileCallback<ibex_bluesky_core.callbacks.HumanReadableFileCallback>` 
+{py:obj}`~ibex_bluesky_core.callbacks.HumanReadableFileCallback` 
 for the "human-readable" files, or 
-{py:obj}`LiveFitLogger<ibex_bluesky_core.callbacks.LiveFitLogger>` 
+{py:obj}`~ibex_bluesky_core.callbacks.LiveFitLogger` 
 for the fit output files. These callbacks may be hidden behind
-{py:obj}`ISISCallbacks<ibex_bluesky_core.callbacks.ISISCallbacks>` which also allows specifying output paths.
+{py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks` which also allows specifying output paths.
 
 See [dae_scan manual system test](https://github.com/ISISComputingGroup/ibex_bluesky_core/blob/main/manual_system_tests/dae_scan.py)
-for an example of how to configure these output paths using {py:obj}`ISISCallbacks<ibex_bluesky_core.callbacks.ISISCallbacks>`.
+for an example of how to configure these output paths using {py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks`.
 
 ### Raw diagnostic data
 
 Raw documents emitted by bluesky are stored in `C:\Instrument\Var\logs\bluesky\raw_documents` - these show the raw 
 data emitted by bluesky scans. The filenames in this directory correspond to bluesky's scan ID, which is printed to 
 the console at the end of each scan, and is also included as metadata in the scientist-facing output files.
 
-These files are written by {py:obj}`ibex_bluesky_core.callbacks.DocLoggingCallback`, which is subscribed
-to the run engine by default in {py:obj}`ibex_bluesky_core.run_engine.get_run_engine`.
+These files are written by {py:obj}`~ibex_bluesky_core.callbacks.DocLoggingCallback`, which is subscribed
+to the run engine by default in {py:obj}`~ibex_bluesky_core.run_engine.get_run_engine`.
 
 ```{note}
 Older raw documents will be moved by the log rotation script to 

doc/plan_stubs/polling.md

@@ -6,4 +6,4 @@ for our usual plotting and fitting callbacks.
 
 Updates from the readable may be dropped if they occur at a higher rate than updates from the motor position.
 
-{py:obj}`ibex_bluesky_core.plans.polling_plan` does not start a bluesky run, so you will need to use a {py:obj}`~bluesky.preprocessors.run_decorator` on an outer plan which calls this plan stub. This is so that _multiple_ continuous moves can be done as part of the same bluesky run.
+{py:obj}`~ibex_bluesky_core.plans.polling_plan` does not start a bluesky run, so you will need to use a {py:obj}`~bluesky.preprocessors.run_decorator` on an outer plan which calls this plan stub. This is so that _multiple_ continuous moves can be done as part of the same bluesky run.

doc/plan_stubs/redefining.md

@@ -5,7 +5,7 @@ occurs, but the reported position changes to the given position.
 
 ## {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor`
 
-The {py:obj}`ibex_bluesky_core.plan_stubs.redefine_motor` plan stub can be used to redefine the current
+The {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor` plan stub can be used to redefine the current
 position of a motor (for example a {py:obj}`~ibex_bluesky_core.devices.block.BlockMot`) to a new value.
 
 The motor does not physically move, but after this plan stub executes, the current position will be defined
@@ -37,7 +37,7 @@ This behaviour can be controlled with the `sleep` keyword argument to
 
 ## {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_refl_parameter`
 
-The {py:obj}`ibex_bluesky_core.plan_stubs.redefine_refl_parameter` plan stub can be used to redefine the current
+The {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_refl_parameter` plan stub can be used to redefine the current
 position of a {py:obj}`~ibex_bluesky_core.devices.reflectometry.ReflParameter` to a new value. 
 
 :::{note}