avoid certain reST syntax errors in documentation

docs/source/example/_export_bluesky_data.md

@@ -13,9 +13,9 @@ First, you have some choices:
   - _one-time_: learn a set of Python commands
   - _occasional_: build Python command (or _callback_) to expedite the steps _for your users_.
   - _always_: write file as data is acquired using a Bluesky
-    [`callback`](https://blueskyproject.io/bluesky/callbacks.html?highlight=callback#overview-of-callbacks) (to the bluesky `RunEngine`)
+    [callback](https://blueskyproject.io/bluesky/callbacks.html?highlight=callback#overview-of-callbacks) (to the bluesky `RunEngine`)
 - What tool(s) will the user(s) be using to **_read_** the data received?
-  - _python_: [`databroker`](https://blueskyproject.io/databroker/)
+  - _python_: [databroker](https://blueskyproject.io/databroker/)
   - _file(s)_: What file format to use?
     - _text_:
       [CSV](https://docs.python.org/3/library/csv.html),
@@ -29,12 +29,12 @@ First, you have some choices:
   - _network_:
     - _[globus](https://www.globus.org/data-transfer)_:
       high-performance data transfers between systems within and across organizations
-    - _[`tiled`](https://blueskyproject.io/tiled/)_:
+    - _[tiled](https://blueskyproject.io/tiled/)_:
       Bluesky **data access** service for data-aware portals and data science tools.
 
 ## databroker-pack
 
-The [`databroker-pack`](https://blueskyproject.io/databroker-pack/) package
+The [databroker-pack](https://blueskyproject.io/databroker-pack/) package
 is used as part of the process to move a subset of a databroker catalog (or the entire catalog).
 
 > The utility `databroker-pack` boxes up Bluesky Runs as a directory of
@@ -157,7 +157,7 @@ Since `md` is a dictionary structure, it is not so easy to write into a CSV file
 #### JSON
 
 While Python provides a
-[`json`](https://docs.python.org/3/library/json.html) package to
+[json](https://docs.python.org/3/library/json.html) package to
 read/write a JSON file, it may be easier to use the `xarray` structure
 returned by the `databroker` from `run.primary.read()` (where  `primary`
 is the name of the document stream named _primary_).  Export the data to
@@ -186,7 +186,7 @@ can be set to `false` if you wish to disable this.
 ### HDF5 files
 
 Python support for the HDF5 format is usally provided through use of the
-[`h5py`](https://www.h5py.org/) package.  NeXus is an example of a specific
+[h5py](https://www.h5py.org/) package.  NeXus is an example of a specific
 
 #### raw
 
@@ -220,7 +220,7 @@ data according to the terms of the file format.
 ### apstools
 
 The
-[`apstools`](https://bcda-aps.github.io/apstools/source/_filewriters.html)
+[apstools](https://bcda-aps.github.io/apstools/source/_filewriters.html)
 package supports automatic data export to NeXus or SPEC data files via
 callbacks.  The support is provided in python `class` definitions that
 handle each of the document types from the `RunEngine`.

docs/source/example/_xafs_scan.ipynb

@@ -212,7 +212,7 @@
     "\n",
     "XAFS scans measure signals from two or more detectors as the incident X-ray energy is varied.  One method is to step the energy where the step size is different depending on the region of the scan.  Steps could be in constant units of energy or _k_ (see above).\n",
     "\n",
-    "We define here a default list of four regions (known here as `segments`), each showing a different feature of units or count time weighting.  This default list is used in the `xafs()` scan below if the caller chooses.  The `get_energies_and_times()` function parses the supplied list of segments and returns a list of `(energy_keV, count_time)` pairs for use in a [`bluesky`](https://blueskyproject.io/bluesky/).[`plans`](https://blueskyproject.io/bluesky/plans.html).[`list_scan()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.list_scan.html#bluesky.plans.list_scan)."
+    "We define here a default list of four regions (known here as `segments`), each showing a different feature of units or count time weighting.  This default list is used in the `xafs()` scan below if the caller chooses.  The `get_energies_and_times()` function parses the supplied list of segments and returns a list of `(energy_keV, count_time)` pairs for use in a [bluesky](https://blueskyproject.io/bluesky/).[plans](https://blueskyproject.io/bluesky/plans.html).[list_scan()](https://blueskyproject.io/bluesky/generated/bluesky.plans.list_scan.html#bluesky.plans.list_scan)."
    ]
   },
   {
@@ -385,7 +385,7 @@
    "source": [
     "## `xafs()` plan\n",
     "\n",
-    "With all the pieces defined, it is time to write a plan to measure the XAFS.  The caller must provide the absorption edge energy (in keV).  A list of segments is optional (will default to `DEFAULT_XAFS_SCAN_SEGMENTS` as defined above) so only the absorption edge energy is required.  Once the inputs are checked for correctness, the absorption calculation is setup in an EPICS userCalc ([`SwaitRecord`](https://apstools.readthedocs.io/en/latest/source/synApps/_swait.html#synapps-swait-record)).  Finally, the 1-D step scan is run by calling [`bp.list_scan()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.list_scan.html#bluesky.plans.list_scan) with lists of energy and count time values for each step."
+    "With all the pieces defined, it is time to write a plan to measure the XAFS.  The caller must provide the absorption edge energy (in keV).  A list of segments is optional (will default to `DEFAULT_XAFS_SCAN_SEGMENTS` as defined above) so only the absorption edge energy is required.  Once the inputs are checked for correctness, the absorption calculation is setup in an EPICS userCalc ([SwaitRecord](https://apstools.readthedocs.io/en/latest/source/synApps/_swait.html#synapps-swait-record)).  Finally, the 1-D step scan is run by calling [bp.list_scan()](https://blueskyproject.io/bluesky/generated/bluesky.plans.list_scan.html#bluesky.plans.list_scan) with lists of energy and count time values for each step."
    ]
   },
   {

docs/source/howto/_basic_aps_info.ipynb

@@ -107,7 +107,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `aps` object is an instance of [`apstools.devices.ApsMachineParametersDevice`](https://bcda-aps.github.io/apstools/latest/api/_devices.html#apstools.devices.aps_machine.ApsMachineParametersDevice)."
+    "The `aps` object is an instance of [apstools.devices.ApsMachineParametersDevice](https://bcda-aps.github.io/apstools/latest/api/_devices.html#apstools.devices.aps_machine.ApsMachineParametersDevice)."
    ]
   },
   {

docs/source/howto/_basic_motor_scaler_scan.ipynb

@@ -26,7 +26,7 @@
    "source": [
     "## Connect the motor\n",
     "\n",
-    "First, import the [`ophyd.EpicsMotor`](https://blueskyproject.io/ophyd/generated/ophyd.epics_motor.EpicsMotor.html?highlight=epicsmotor#ophyd.epics_motor.EpicsMotor) (class) definition.  This Python class from `ophyd` is the best representation of the synApps [motor](https://github.com/epics-modules/motor) record."
+    "First, import the [ophyd.EpicsMotor](https://blueskyproject.io/ophyd/generated/ophyd.epics_motor.EpicsMotor.html?highlight=epicsmotor#ophyd.epics_motor.EpicsMotor) (class) definition.  This Python class from `ophyd` is the best representation of the synApps [motor](https://github.com/epics-modules/motor) record."
    ]
   },
   {
@@ -231,7 +231,7 @@
    "source": [
     "## Connect the scaler\n",
     "\n",
-    "The `ophyd` package provides two representations of the synApps [scaler](https://github.com/epics-modules/scaler) record ([`EpicsScaler`](https://blueskyproject.io/ophyd/reference/builtin-devices.html#epicsscaler) and [`ScalerCH`](https://blueskyproject.io/ophyd/reference/builtin-devices.html#scalerch)).  My _opinion_ is that the `ScalerCH` class provides the representation most compatible with use at the APS.\n",
+    "The `ophyd` package provides two representations of the synApps [scaler](https://github.com/epics-modules/scaler) record ([EpicsScaler](https://blueskyproject.io/ophyd/reference/builtin-devices.html#epicsscaler) and [ScalerCH](https://blueskyproject.io/ophyd/reference/builtin-devices.html#scalerch)).  My _opinion_ is that the `ScalerCH` class provides the representation most compatible with use at the APS.\n",
     "\n",
     "As before, import the ophyd class:"
    ]
@@ -843,7 +843,7 @@
    "source": [
     "## First scan\n",
     "\n",
-    "The standard plans provided in [`bluesky.plans`](https://blueskyproject.io/bluesky/plans.html#pre-assembled-plans) are sufficient for many needs, so import them and, in the same command, give the package a short name (`bp`) since it is used frequently."
+    "The standard plans provided in [bluesky.plans](https://blueskyproject.io/bluesky/plans.html#pre-assembled-plans) are sufficient for many needs, so import them and, in the same command, give the package a short name (`bp`) since it is used frequently."
    ]
   },
   {
@@ -861,7 +861,7 @@
    "id": "c3c753bb",
    "metadata": {},
    "source": [
-    "The [`scan()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.scan.html#bluesky.plans.scan) plan is flexible and will be used here to scan scaler *vs.* motor.  The first argument is the *list* of detectors to be recorded.  Here, we give the scaler object `vsc16`.  The next argument is the positioner object, then start and end positions, finally, the number of points to be collected.\n",
+    "The [scan()](https://blueskyproject.io/bluesky/generated/bluesky.plans.scan.html#bluesky.plans.scan) plan is flexible and will be used here to scan scaler *vs.* motor.  The first argument is the *list* of detectors to be recorded.  Here, we give the scaler object `vsc16`.  The next argument is the positioner object, then start and end positions, finally, the number of points to be collected.\n",
     "\n",
     "Observe that we do not run the scan directly, but rather give the scan to the `RE()` object.  The `RE()` object will run the scan, performing each of the actions defined by the scan, but also handle the additional tasks of managing the data acquisition process, publishing data to all subscribers (here: databroker and BestEffortCallback) and checking for updates from EPICS and checking if the run must be interrupted either by user request or some other observation.  (We have not configured any of those other observations in this simple example.)"
    ]
@@ -1347,11 +1347,11 @@
     "\n",
     "   _Hint_: `logger.info(\"text: %s  value: %g\", s1, v2, ...)`\n",
     "\n",
-    "   Consider examples as used in [`peak_finder_example.py`](instrument/plans/peak_finder_example.py).\n",
+    "   Consider examples as used in `instrument/plans/peak_finder_example.py`.\n",
     "   See the [Python logging tutorial](https://docs.python.org/3/howto/logging.html) for more information.\n",
     "1. Write a custom plan that accepts user-provided metadata.\n",
     "\n",
-    "   _Hint_: [`bp.scan()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.scan.html#bluesky.plans.scan) has the `md` keyword argument (_kwarg_) that accepts a dictionary of _key: value_ pairs as the metadata when the plan is run.  Your custom plan should accept the same kwarg and pass this to `bp.scan(md=the_dictionary)`, possibly after adding some of its own keys to the metadata."
+    "   _Hint_: [bp.scan()](https://blueskyproject.io/bluesky/generated/bluesky.plans.scan.html#bluesky.plans.scan) has the `md` keyword argument (_kwarg_) that accepts a dictionary of _key: value_ pairs as the metadata when the plan is run.  Your custom plan should accept the same kwarg and pass this to `bp.scan(md=the_dictionary)`, possibly after adding some of its own keys to the metadata."
    ]
   }
  ],

docs/source/howto/_count_scaler.ipynb

@@ -160,7 +160,7 @@
    "id": "7cc70fa9",
    "metadata": {},
    "source": [
-    "The _easiest_ way to count the `scaler` object is to use the [`%ct`](https://blueskyproject.io/bluesky/magics.html?highlight=label#taking-a-reading-using-ct-post-v1-3-0) bluesky magic command, which counts all objects with the `detectors` label.\n",
+    "The _easiest_ way to count the `scaler` object is to use the [%ct](https://blueskyproject.io/bluesky/magics.html?highlight=label#taking-a-reading-using-ct-post-v1-3-0) bluesky magic command, which counts all objects with the `detectors` label.\n",
     "\n",
     "Note that the various magic commands are only available from the command line, not for use in a bluesky plan function."
    ]
@@ -427,7 +427,7 @@
    "source": [
     "### use bluesky (the package) to count the scaler\n",
     "\n",
-    "Now, use the bluesky [RunEngine](https://blueskyproject.io/bluesky/generated/bluesky.run_engine.RunEngine.html?highlight=runengine#bluesky.run_engine.RunEngine) (`RE`) to count `scaler1`.  We'll use the bluesky plan ([`bp`](https://blueskyproject.io/bluesky/plans.html?highlight=count#pre-assembled-plans)) called [`count()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  To be consistent with the result returned from `%ct`, we'll include the `noisy` detector."
+    "Now, use the bluesky [RunEngine](https://blueskyproject.io/bluesky/generated/bluesky.run_engine.RunEngine.html?highlight=runengine#bluesky.run_engine.RunEngine) (`RE`) to count `scaler1`.  We'll use the bluesky plan ([bp](https://blueskyproject.io/bluesky/plans.html?highlight=count#pre-assembled-plans)) called [count()](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  To be consistent with the result returned from `%ct`, we'll include the `noisy` detector."
    ]
   },
   {
@@ -887,7 +887,7 @@
    "id": "94e8851a",
    "metadata": {},
    "source": [
-    "As a last action in this section, use the [`listruns()`](https://bcda-aps.github.io/apstools/latest/api/_utils.html#apstools.utils.list_runs.listruns) command from *apstools* to show the (default: 20) most recent runs in the database.  The table shows a short version of the run's unique identifier (`short_uid`), and other more obvious columns of information, truncated to avoid lengthy output.  The name of the [databroker *catalog*](https://blueskyproject.io/databroker/index.html) (`class_2021_03`) is shown before the table."
+    "As a last action in this section, use the [listruns()](https://bcda-aps.github.io/apstools/latest/api/_utils.html#apstools.utils.list_runs.listruns) command from *apstools* to show the (default: 20) most recent runs in the database.  The table shows a short version of the run's unique identifier (`short_uid`), and other more obvious columns of information, truncated to avoid lengthy output.  The name of the [databroker *catalog*](https://blueskyproject.io/databroker/index.html) (`class_2021_03`) is shown before the table."
    ]
   },
   {