Merge pull request #928 from BCDA-APS/927-formatting-problems-in-docs

remove problematic nested formatting in notebooks

docs/source/examples/de_0_adsim_hdf5_basic.ipynb

@@ -385,7 +385,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We must configure `adsimdet` so the HDF5 plugin (by its attribute name `hdf1`) will be called during `adsimdet.read()`, as used by data acquisition.  This plugin is already `enabled` (above) but we must change the [`kind`](https://blueskyproject.io/ophyd/user_v1/reference/signals.html#kind) attribute.  Ophyd support will check this attribute to see if the plugin should be [`read`](https://blueskyproject.io/ophyd/user_v1/tutorials/device.html#assign-a-kind-to-components) during data acquisition.  If we don't change this, the area detector image(s) will not be reported in the run's documents.\n",
+    "We must configure `adsimdet` so the HDF5 plugin (by its attribute name `hdf1`) will be called during `adsimdet.read()`, as used by data acquisition.  This plugin is already `enabled` (above) but we must change the [kind](https://blueskyproject.io/ophyd/user_v1/reference/signals.html#kind) attribute.  Ophyd support will check this attribute to see if the plugin should be [read](https://blueskyproject.io/ophyd/user_v1/tutorials/device.html#assign-a-kind-to-components) during data acquisition.  If we don't change this, the area detector image(s) will not be reported in the run's documents.\n",
     "\n",
     "**Note**: Here, we assign the `kind` attribute by number `3`, a shorthand which is interpreted by ophyd as `ophyd.Kind.config | ophyd.Kind.normal`."
    ]

docs/source/examples/de_scaler_motor_flyer.ipynb_i763

@@ -166,7 +166,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Augment the *standard* (a.k.a. bluesky pre-assembled) [`bp.fly()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.fly.html#bluesky.plans.fly) plan to save the peak statistics to a separate stream in the run after the fly scan is complete."
+    "Augment the *standard* (a.k.a. bluesky pre-assembled) [bp.fly()](https://blueskyproject.io/bluesky/generated/bluesky.plans.fly.html#bluesky.plans.fly) plan to save the peak statistics to a separate stream in the run after the fly scan is complete."
    ]
   },
   {

docs/source/examples/fw_specfile_example.ipynb

@@ -819,7 +819,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's view file `spec1.dat` from disk storage (using the [`pycat`](https://ipython.readthedocs.io/en/stable/interactive/magics.html?highlight=pycat#magic-pycat) IPython magic function):"
+    "Let's view file `spec1.dat` from disk storage (using the [pycat](https://ipython.readthedocs.io/en/stable/interactive/magics.html?highlight=pycat#magic-pycat) IPython magic function):"
    ]
   },
   {

docs/source/examples/ho_contingency.ipynb

@@ -95,7 +95,7 @@
     "\n",
     "#### Exceptions\n",
     "\n",
-    "An unhandled Python [`Exception`](https://docs.python.org/3/library/exceptions.html) will terminate a plan run by `bluesky.RunEngine`.\n",
+    "An unhandled Python [Exception](https://docs.python.org/3/library/exceptions.html) will terminate a plan run by `bluesky.RunEngine`.\n",
     "\n",
     "Next, we create `MyException`,  a custom exception, and `my_plan`, a bluesky plan that can raise this custom exception.  If `MyException` is raised, then `bp.count` will not be run and  `After count` will not be printed.\n",
     "\n",
@@ -312,7 +312,7 @@
     "**Exception handling in generator coroutines**\n",
     "\n",
     "Generator coroutines [expose exception throwing](https://tacaswell.github.io/coroutines-i.html) as a user communication channel.  This means\n",
-    "there is some [in-band encoding](https://youtu.be/iKzOBWOHGFE?si=XAtQKhk3eHboHcL-&t=1011) of Python's control exceptions with the users exceptions.  When the `close()` [method](https://docs.python.org/3/reference/expressions.html#generator.close) is called on a generator coroutine, Python will throw a  [`GeneratorExit`](https://docs.python.org/3/library/exceptions.html#GeneratorExit) exception into the coroutine.  If you catch this exception and try to yield another `Msg`, either explicitly in an `except` block or in a `finally` block, Python will raise a `RuntimeError` at the call site.\n",
+    "there is some [in-band encoding](https://youtu.be/iKzOBWOHGFE?si=XAtQKhk3eHboHcL-&t=1011) of Python's control exceptions with the users exceptions.  When the `close()` [method](https://docs.python.org/3/reference/expressions.html#generator.close) is called on a generator coroutine, Python will throw a  [GeneratorExit](https://docs.python.org/3/library/exceptions.html#GeneratorExit) exception into the coroutine.  If you catch this exception and try to yield another `Msg`, either explicitly in an `except` block or in a `finally` block, Python will raise a `RuntimeError` at the call site.\n",
     "\n",
     "If you want to use `try..except..else..finally` directly, you must handle this case.  See the source of these decorators for a guide.\n",
     "\n",
@@ -763,7 +763,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The shutter will be zero when closed, and one when open. Looking at the list of pre-defined [suspenders](https://blueskyproject.io/bluesky/state-machine.html#built-in-suspenders), [`bluesky.suspenders.SuspendBoolLow`](https://blueskyproject.io/bluesky/generated/bluesky.suspenders.SuspendBoolLow.html#bluesky.suspenders.SuspendBoolLow) fits this pattern.  Let's tell it to wait 5 seconds after the shutters open before releasing the suspension on the RunEngine."
+    "The shutter will be zero when closed, and one when open. Looking at the list of pre-defined [suspenders](https://blueskyproject.io/bluesky/state-machine.html#built-in-suspenders), [bluesky.suspenders.SuspendBoolLow](https://blueskyproject.io/bluesky/generated/bluesky.suspenders.SuspendBoolLow.html#bluesky.suspenders.SuspendBoolLow) fits this pattern.  Let's tell it to wait 5 seconds after the shutters open before releasing the suspension on the RunEngine."
    ]
   },
   {

docs/source/examples/ho_list_control_objects.ipynb

@@ -619,7 +619,7 @@
     "## `.summary()` method\n",
     "\n",
     "Every object using `ophyd.Device` (or a subclass) has a\n",
-    "[`.summary()`](https://github.com/bluesky/ophyd/blob/285b0c75da67c935a8073481d6442362723b127b/ophyd/device.py#L1209-L1213)\n",
+    "[.summary()](https://github.com/bluesky/ophyd/blob/285b0c75da67c935a8073481d6442362723b127b/ophyd/device.py#L1209-L1213)\n",
     "method to describe its internal structure.  (Note: a `Signal` does not have a\n",
     "`.summary()` method.)\n",
     "\n",

docs/source/examples/pl_excel_scan.ipynb

@@ -25,7 +25,7 @@
     "to generalize.given a spreadsheet (named ``sample_example.xlsx``)\n",
     "with content as shown in the next figure:\n",
     "\n",
-    "![`sample_example.xlsx`](../resources/sample_example.jpg)\n",
+    "![sample_example.xlsx](../resources/sample_example.jpg)\n",
     "\n",
     "**Tip**: Place the column labels on the fourth row of the spreadsheet, starting\n",
     "in the first column. The actions start on the next row.  The first blank row\n",