From 3dbce1d61f900bb094aa89d4630b42b7619e4d1e Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 10:14:46 -0600
Subject: [PATCH 01/11] upload built documentation as artifact from github
 actions workflow (#275)

* MNT #274 rename consistent with other projects

* CI #274 add upload to workflow and re-arrange per murky project

* WIP #274 Diagnostic

* WIP #274 find the built docs

* CI #274 re-enable upload & deploy steps

* CI #274 put a name on the file
---
 .github/workflows/{pages.yml => docs.yml} | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)
 rename .github/workflows/{pages.yml => docs.yml} (77%)

diff --git a/.github/workflows/pages.yml b/.github/workflows/docs.yml
similarity index 77%
rename from .github/workflows/pages.yml
rename to .github/workflows/docs.yml
index ba8a4bca..ba7e2940 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/docs.yml
@@ -27,8 +27,8 @@ defaults:
 jobs:
 
   pages:
-
-    runs-on: ubuntu-20.04
+    name: Publish documentation
+    runs-on: ubuntu-latest
 
     steps:
 
@@ -45,13 +45,23 @@ jobs:
     - name: Set time zone
       run: echo "TZ=America/Chicago" >> "$GITHUB_ENV"
 
-    - id: deployment
+    - name: Sphinx build
+      id: deployment
       uses: sphinx-notes/pages@v3
       with:
         documentation_path: ./docs/source
         publish: false
         requirements_path: ./docs/requirements.txt
 
+    - name: Diagnostic
+      run: ls -lAFgh ${{ steps.deployment.outputs.artifact }}
+
+    - name: Upload Docs ZIP file as artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: bluesky_training-docs
+        path: ${{ steps.deployment.outputs.artifact }}
+    
     - uses: peaceiris/actions-gh-pages@v3
       if: ${{ github.event.inputs.deploy }}
       with:

From d408d602292a642a7ddb3a19d0f3cb97fbee451f Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@gmail.com>
Date: Mon, 26 Feb 2024 10:37:47 -0600
Subject: [PATCH 02/11] DOC #136 restore coverage badge

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 38714dd1..cdc8e42e 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,9 @@ beamlines to use the [Bluesky](https://blueskyproject.io) framework.
 - a [list of APS instrument](https://github.com/BCDA-APS/bluesky_training/wiki/)
   repositories
 
-Unit Tests | License | GH tag
+Unit Tests | License | GH tag | Code Coverage
 --- | --- | ---
-[![Unit Tests](https://github.com/BCDA-APS/bluesky_training/workflows/Unit%20Tests/badge.svg)](https://github.com/BCDA-APS/bluesky_training/actions/workflows/unit_tests.yml) | [![license: ANL](https://img.shields.io/badge/license-ANL-brightgreen)](/LICENSE.txt) | [![tag](https://img.shields.io/github/tag/BCDA-APS/bluesky_training.svg)](https://github.com/BCDA-APS/bluesky_training/tags)
+[![Unit Tests](https://github.com/BCDA-APS/bluesky_training/workflows/Unit%20Tests/badge.svg)](https://github.com/BCDA-APS/bluesky_training/actions/workflows/unit_tests.yml) | [![license: ANL](https://img.shields.io/badge/license-ANL-brightgreen)](/LICENSE.txt) | [![tag](https://img.shields.io/github/tag/BCDA-APS/bluesky_training.svg)](https://github.com/BCDA-APS/bluesky_training/tags) | [![Coverage Status](https://coveralls.io/repos/github/BCDA-APS/bluesky_training/badge.svg?branch=main)](https://coveralls.io/github/BCDA-APS/bluesky_training?branch=main)
 
 <!-- take note of
 

From 523a6074a6cefb87e2173a6ab70e4bf4dbf7fe60 Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@gmail.com>
Date: Mon, 26 Feb 2024 10:38:16 -0600
Subject: [PATCH 03/11] DOC syntax

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cdc8e42e..cd6ed132 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ beamlines to use the [Bluesky](https://blueskyproject.io) framework.
   repositories
 
 Unit Tests | License | GH tag | Code Coverage
---- | --- | ---
+--- | --- | --- | ---
 [![Unit Tests](https://github.com/BCDA-APS/bluesky_training/workflows/Unit%20Tests/badge.svg)](https://github.com/BCDA-APS/bluesky_training/actions/workflows/unit_tests.yml) | [![license: ANL](https://img.shields.io/badge/license-ANL-brightgreen)](/LICENSE.txt) | [![tag](https://img.shields.io/github/tag/BCDA-APS/bluesky_training.svg)](https://github.com/BCDA-APS/bluesky_training/tags) | [![Coverage Status](https://coveralls.io/repos/github/BCDA-APS/bluesky_training/badge.svg?branch=main)](https://coveralls.io/github/BCDA-APS/bluesky_training?branch=main)
 
 <!-- take note of

From bc8e7679a3a1fd1ef902b54bd8c876c7039665fc Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@gmail.com>
Date: Mon, 26 Feb 2024 10:41:00 -0600
Subject: [PATCH 04/11] DOC cite installation checklist on main page

---
 README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index cd6ed132..2e470798 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,9 @@ beamlines to use the [Bluesky](https://blueskyproject.io) framework.
 
 - [HowTo guides, tutorials, & references](https://bcda-aps.github.io/bluesky_training/)
   demonstrating use of the Bluesky framework at a typical beamline.
-- a [template](./bluesky/) for beamlines to configure their instrument
-- a [list of APS instrument](https://github.com/BCDA-APS/bluesky_training/wiki/)
+- A [template](./bluesky/) for beamlines to configure their instrument.
+- A [checklist](https://bcda-aps.github.io/bluesky_training/instrument/_install_new_instrument.html#installation-checklist) to install a new instrument.
+- A [list of APS instrument](https://github.com/BCDA-APS/bluesky_training/wiki/)
   repositories
 
 Unit Tests | License | GH tag | Code Coverage

From 7d4f5539bc22bfcefd443babd902e0aee394ba4c Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 10:48:09 -0600
Subject: [PATCH 05/11] changes to configure new installation (#281)

* DOC #213 release notes

* MNT #213 relocate & remove clutter from home directory
---
 CHANGES.rst                                | 1 +
 bluesky/instrument/framework/initialize.py | 2 +-
 bluesky/instrument/iconfig.yml             | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index a9577bbb..74e824be 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -45,6 +45,7 @@ Maintenance
 
 * Drop the (unused now) *stdlogpj* package for configuring Python's *logging*.
 * Environment for bluesky_2024_1.
+* Updates (from learned 2-ID) for new installations.
 
 
 v1.0.1
diff --git a/bluesky/instrument/framework/initialize.py b/bluesky/instrument/framework/initialize.py
index 2b92c672..1efb7abd 100644
--- a/bluesky/instrument/framework/initialize.py
+++ b/bluesky/instrument/framework/initialize.py
@@ -47,7 +47,7 @@
 def get_md_path():
     path = iconfig.get("RUNENGINE_MD_PATH")
     if path is None:
-        path = pathlib.Path.home() / "Bluesky_RunEngine_md"
+        path = pathlib.Path.home() / ".config" / "Bluesky_RunEngine_md"
     else:
         path = pathlib.Path(path)
     logger.info("RunEngine metadata saved in directory: %s", str(path))
diff --git a/bluesky/instrument/iconfig.yml b/bluesky/instrument/iconfig.yml
index 32b0988f..79a51d5f 100644
--- a/bluesky/instrument/iconfig.yml
+++ b/bluesky/instrument/iconfig.yml
@@ -41,7 +41,7 @@ WRITE_SPEC_DATA_FILES: true
 
 # Directory to "autosave" the RE.md dictionary (uses PersistentDict)
 # Uncomment and modify to change from the default.
-# RUNENGINE_MD_PATH: /home/USERNAME/Bluesky_RunEngine_md
+# RUNENGINE_MD_PATH: /home/USERNAME/.config/Bluesky_RunEngine_md
 
 # override default control layer for ophyd
 # if undefined, defaults to PyEpics

From cb005dbb5e11b841a725880a0703712499c9c584 Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 10:51:22 -0600
Subject: [PATCH 06/11] Cite hello world in installation checklist, generalize
 for queueserver (#279)

* MNT @241 suggested changes

* DOC #241 reference the Hello World! notebook
---
 CHANGES.rst                                        | 1 +
 bluesky/user/quick_hello.py                        | 4 ++--
 docs/source/instrument/_install_new_instrument.rst | 3 +--
 docs/source/instrument/_test_new_instrument.md     | 4 +++-
 4 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 74e824be..76b14f24 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -43,6 +43,7 @@ New Features
 Maintenance
 ------------
 
+* Add 'Hello, World!' test to installation checklist.
 * Drop the (unused now) *stdlogpj* package for configuring Python's *logging*.
 * Environment for bluesky_2024_1.
 * Updates (from learned 2-ID) for new installations.
diff --git a/bluesky/user/quick_hello.py b/bluesky/user/quick_hello.py
index a6ac9f91..e0cc873f 100644
--- a/bluesky/user/quick_hello.py
+++ b/bluesky/user/quick_hello.py
@@ -1,5 +1,5 @@
 """
-Hello, World! demo for bluesky-queueserver testing.
+Demo 'Hello, World!' for testing, including bluesky-queueserver.
 
 EXAMPLE::
 
@@ -41,4 +41,4 @@ class HelloDevice(Device):
 
 def hello_world():
     """Simple bluesky plan for demonstrating Hello, World!."""
-    yield from bp.count([hello_device], md=dict(title="test QS"))
+    yield from bp.count([hello_device], md=dict(subtitle="test Bluesky"))
diff --git a/docs/source/instrument/_install_new_instrument.rst b/docs/source/instrument/_install_new_instrument.rst
index d7ca6521..0d1d44f5 100644
--- a/docs/source/instrument/_install_new_instrument.rst
+++ b/docs/source/instrument/_install_new_instrument.rst
@@ -17,6 +17,7 @@ to the documentation for each step.
 #. `create conda environment <https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html>`__
 #. `configure IPython profile startup <https://bcda-aps.github.io/bluesky_training/reference/_ipython.html>`__
 #. `configure bash with environment variable and alias <https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html#create-an-alias-to-activate-the-bluesky-environment>`__
+#. Verify the installation by running the `Hello, World! tutorial. <https://bcda-aps.github.io/bluesky_training/tutor/hello_world.html>`__
 #. create soft link:  ``ln -s ${HOME}/bluesky/blueskyStarter.sh ~/bin/``
 #. Assign a MongoDB catalog for databroker: `instructions for BCDA <https://git.aps.anl.gov/bcda/bluesky-catalogs/-/blob/master/README.md>`__
 #. `databroker catalog configuration <https://bcda-aps.github.io/bluesky_training/instrument/_configure_databroker.html#setup-your-databroker-catalog-configuration>`__
@@ -346,8 +347,6 @@ Note that the bluesky team recommends GitHub. (Why is that? See section
          </ul>
 
 
-
-
 The next steps are common to both web-based repositories (GitHub and GitLab):
 
 - copy the remote `repository URL <https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#choosing-a-url-for-your-remote-repository>`_, for example,
diff --git a/docs/source/instrument/_test_new_instrument.md b/docs/source/instrument/_test_new_instrument.md
index 9604f3af..7eb8ba7f 100644
--- a/docs/source/instrument/_test_new_instrument.md
+++ b/docs/source/instrument/_test_new_instrument.md
@@ -10,7 +10,9 @@ Visit <a href=https://bcda-aps.github.io/bluesky_training/instrument/_install_ne
 
 <details>
 <summary>How to test my Bluesky installation?</summary>
-Visit <a href=https://bcda-aps.github.io/bluesky_training/tutor/_hello_word.html> Hello World</a>.
+Test (verify) the installation by running the <a
+href=https://bcda-aps.github.io/bluesky_training/tutor/hello_world.html>Hello, World!</a>
+tutorial.
 </details>
 
 <br>

From 846eafcb68622f0fafe68f8fbf1cc9f600a46d84 Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 10:51:49 -0600
Subject: [PATCH 07/11] refactor and combine for EPICS scan_id PV (#280)

* MNT #229 refactor

* STY #229 per 'ruff check'
---
 bluesky/instrument/epics_signal_config.py  | 19 ++++++---
 bluesky/instrument/framework/initialize.py | 45 +++-------------------
 2 files changed, 19 insertions(+), 45 deletions(-)

diff --git a/bluesky/instrument/epics_signal_config.py b/bluesky/instrument/epics_signal_config.py
index 5ddfbf68..823aa9b7 100644
--- a/bluesky/instrument/epics_signal_config.py
+++ b/bluesky/instrument/epics_signal_config.py
@@ -9,16 +9,16 @@
 
 import logging
 
+from ophyd.signal import EpicsSignalBase
+
 logger = logging.getLogger(__name__)
 logger.info(__file__)
 
-from . import iconfig
-from ophyd.signal import EpicsSignal
-from ophyd.signal import EpicsSignalBase
+from . import iconfig  # noqa
 
 
-# set default timeout for all EpicsSignal connections & communications
-# always first, before ANY ophyd EPICS-based signals are created
+# Set default timeout for all EpicsSignal connections & communications.
+# Always call first, before ANY ophyd EPICS-based signals are created.
 TIMEOUT = 60
 if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
     EpicsSignalBase.set_defaults(
@@ -33,7 +33,10 @@
     logger.info("Using RunEngine metadata for scan_id")
     scan_id_epics = None
 else:
+    from ophyd.signal import EpicsSignal
+
     logger.info("Using EPICS PV %s for scan_id", pvname)
+    # Must not call _before_ default timeouts are set.
     scan_id_epics = EpicsSignal(pvname, name="scan_id_epics")
 
 
@@ -41,17 +44,21 @@ def epics_scan_id_source(*args, **kwargs):
     """
     Callback function for RunEngine.  Returns *next* scan_id to be used.
 
+    * Ignore args and kwargs.
     * Get current scan_id from PV.
     * Apply lower limit of zero.
     * Increment.
     * Set PV with new value.
     * Return new value.
+
+    Exception will be raised if PV is not connected when next
+    ``bluesky.plan_stubs.open_run()`` is called.
     """
     if scan_id_epics is None:
         raise RuntimeError(
             "epics_scan_id_source() called when"
             " 'RUN_ENGINE_SCAN_ID_PV' is"
-            "undefined in 'iconfig.yml' file."
+            " undefined in 'iconfig.yml' file."
         )
     new_scan_id = max(scan_id_epics.get(), 0) + 1
     scan_id_epics.put(new_scan_id)
diff --git a/bluesky/instrument/framework/initialize.py b/bluesky/instrument/framework/initialize.py
index 1efb7abd..49fdb551 100644
--- a/bluesky/instrument/framework/initialize.py
+++ b/bluesky/instrument/framework/initialize.py
@@ -109,47 +109,14 @@ def get_md_path():
 # diagnostics
 # RE.msg_hook = ts_msg_hook
 
-# set default timeout for all EpicsSignal connections & communications
-TIMEOUT = 60
-if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
-    EpicsSignalBase.set_defaults(
-        auto_monitor=True,
-        timeout=iconfig.get("PV_READ_TIMEOUT", TIMEOUT),
-        write_timeout=iconfig.get("PV_WRITE_TIMEOUT", TIMEOUT),
-        connection_timeout=iconfig.get("PV_CONNECTION_TIMEOUT", TIMEOUT),
-    )
-
-# Create a registry of ophyd devices
-registry = Registry(auto_register=True)
-
-_pv = iconfig.get("RUN_ENGINE_SCAN_ID_PV")
-if _pv is None:
-    logger.info("Using RunEngine metadata for scan_id")
-else:
-    from ophyd import EpicsSignal
-
-    logger.info("Using EPICS PV %s for scan_id", _pv)
-    scan_id_epics = EpicsSignal(_pv, name="scan_id_epics")
-
-    def epics_scan_id_source(_md):
-        """
-        Callback function for RunEngine.  Returns *next* scan_id to be used.
-
-        * Ignore metadata dictionary passed as argument.
-        * Get current scan_id from PV.
-        * Apply lower limit of zero.
-        * Increment (so that scan_id numbering starts from 1).
-        * Set PV with new value.
-        * Return new value.
-
-        Exception will be raised if PV is not connected when next
-        ``bps.open_run()`` is called.
-        """
-        new_scan_id = max(scan_id_epics.get(), 0) + 1
-        scan_id_epics.put(new_scan_id)
-        return new_scan_id
+if iconfig.get("RUN_ENGINE_SCAN_ID_PV") is not None:
+    from ..epics_signal_config import epics_scan_id_source
+    from ..epics_signal_config import scan_id_epics
 
     # tell RunEngine to use the EPICS PV to provide the scan_id.
     RE.scan_id_source = epics_scan_id_source
     scan_id_epics.wait_for_connection()
     RE.md["scan_id"] = scan_id_epics.get()
+
+# Create a registry of ophyd devices
+registry = Registry(auto_register=True)

From 8e757ed6e50d3718ac1f86dbcb397d163bff59af Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 10:59:34 -0600
Subject: [PATCH 08/11] DOC #215 (#276)

---
 CHANGES.rst           | 3 ++-
 docs/source/index.rst | 3 +++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 76b14f24..e5f730e4 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -46,7 +46,8 @@ Maintenance
 * Add 'Hello, World!' test to installation checklist.
 * Drop the (unused now) *stdlogpj* package for configuring Python's *logging*.
 * Environment for bluesky_2024_1.
-* Updates (from learned 2-ID) for new installations.
+* Updates (learned from 2-ID) for new installations.
+* Various documentation updates.
 
 
 v1.0.1
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d06c7651..d32c0c75 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,6 +17,9 @@ serves as a template for new beamline installations.
    files which do not start with a "_" are added explicitly to the toctree in
    the `index.rst` file of that folder.
 
+In addition to these highlights, additional content is available in each section
+of the documentation.
+
 - :ref:`howto`
    -  `Bluesky Cheat Sheet <howto/bluesky_cheat_sheet.md>`_:
       First Steps to use Bluesky after installation.

From 38189ef390890a6a4e09ae85a5ebe1bb6d845f64 Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 12:22:57 -0600
Subject: [PATCH 09/11] DOC #167 avoid reST syntax errors (#272)

---
 docs/source/example/_export_bluesky_data.md   | 14 ++++++-------
 docs/source/example/_xafs_scan.ipynb          |  4 ++--
 docs/source/howto/_basic_aps_info.ipynb       |  2 +-
 .../howto/_basic_motor_scaler_scan.ipynb      | 12 +++++------
 docs/source/howto/_count_scaler.ipynb         |  6 +++---
 .../howto/_custom_heater_positioner.ipynb     | 14 ++++++-------
 docs/source/howto/_custom_plan.ipynb          |  2 +-
 .../source/howto/_dynamic_limits_2motor.ipynb |  4 ++--
 docs/source/howto/_images_darks_flats.ipynb   |  2 +-
 .../howto/_synapps_sscan_1d_flyer.ipynb       |  2 +-
 .../_configure_bluesky_instrument.md          | 10 +++++-----
 .../instrument/_configure_databroker.md       |  2 +-
 docs/source/instrument/_get_spec_config.md    |  2 +-
 docs/source/instrument/bluesky_class.yml      | 13 ++++++++++++
 .../instrument/describe_instrument.ipynb      | 20 +++++++++----------
 docs/source/instrument/guide.md               | 14 ++++++-------
 docs/source/tutor/_aps101_notes.md            |  6 +++---
 docs/source/tutor/_basic_a.ipynb              |  4 ++--
 docs/source/tutor/_command_review.ipynb       |  2 +-
 docs/source/tutor/_lesson1.ipynb              | 10 +++++-----
 docs/source/tutor/_lesson2.ipynb              |  2 +-
 docs/source/tutor/_lesson3a.ipynb             |  2 +-
 docs/source/tutor/_lesson3b.ipynb             |  2 +-
 docs/source/tutor/_lesson5a.ipynb             |  2 +-
 docs/source/tutor/_lesson6.ipynb              |  2 +-
 docs/source/tutor/_lesson7.ipynb              | 14 ++++---------
 docs/source/tutor/connect_epics.ipynb         |  2 +-
 27 files changed, 89 insertions(+), 82 deletions(-)
 create mode 100644 docs/source/instrument/bluesky_class.yml

diff --git a/docs/source/example/_export_bluesky_data.md b/docs/source/example/_export_bluesky_data.md
index 7605f7ce..239f526e 100644
--- a/docs/source/example/_export_bluesky_data.md
+++ b/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`.
diff --git a/docs/source/example/_xafs_scan.ipynb b/docs/source/example/_xafs_scan.ipynb
index d08ba926..b8848deb 100644
--- a/docs/source/example/_xafs_scan.ipynb
+++ b/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."
    ]
   },
   {
diff --git a/docs/source/howto/_basic_aps_info.ipynb b/docs/source/howto/_basic_aps_info.ipynb
index 9a52d1f8..da0a9fd9 100644
--- a/docs/source/howto/_basic_aps_info.ipynb
+++ b/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)."
    ]
   },
   {
diff --git a/docs/source/howto/_basic_motor_scaler_scan.ipynb b/docs/source/howto/_basic_motor_scaler_scan.ipynb
index 743617d8..fce3211a 100644
--- a/docs/source/howto/_basic_motor_scaler_scan.ipynb
+++ b/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."
    ]
   }
  ],
diff --git a/docs/source/howto/_count_scaler.ipynb b/docs/source/howto/_count_scaler.ipynb
index d4b4f7a9..6e7e302b 100644
--- a/docs/source/howto/_count_scaler.ipynb
+++ b/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."
    ]
   },
   {
diff --git a/docs/source/howto/_custom_heater_positioner.ipynb b/docs/source/howto/_custom_heater_positioner.ipynb
index 2645f17e..0675516c 100644
--- a/docs/source/howto/_custom_heater_positioner.ipynb
+++ b/docs/source/howto/_custom_heater_positioner.ipynb
@@ -24,7 +24,7 @@
     "\n",
     "Simulate a temperature controller with heater and cooling features.  Use it as a positioner.\n",
     "\n",
-    "A temperature sensor can be [simulated](https://github.com/epics-modules/optics/blob/fdf5bc3c2731ba6769b62e71628fe3018c8245e3/opticsApp/Db/fb_epid.db#L236-L270) with a single synApps [`swait`](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/swaitRecord.html) record.  The `swait` record  has 16 fields for input values, either as constants or values from other EPICS PVs.  Via a custom calculation [expression](https://github.com/epics-modules/optics/blob/fdf5bc3c2731ba6769b62e71628fe3018c8245e3/opticsApp/Db/fb_epid.db#L262), a simulated temperature sensor value is computed.\n",
+    "A temperature sensor can be [simulated](https://github.com/epics-modules/optics/blob/fdf5bc3c2731ba6769b62e71628fe3018c8245e3/opticsApp/Db/fb_epid.db#L236-L270) with a single synApps [swait](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/swaitRecord.html) record.  The `swait` record  has 16 fields for input values, either as constants or values from other EPICS PVs.  Via a custom calculation [expression](https://github.com/epics-modules/optics/blob/fdf5bc3c2731ba6769b62e71628fe3018c8245e3/opticsApp/Db/fb_epid.db#L262), a simulated temperature sensor value is computed.\n",
     "\n",
     "<details>\n",
     "\n",
@@ -48,9 +48,9 @@
     "\n",
     "## Overview\n",
     "\n",
-    "A _PID_ loop (see below) has been [paired](https://github.com/epics-modules/optics/blob/master/opticsApp/Db/fb_epid.db) with the simulated temperature using the synApps [`epid`](https://epics.anl.gov/bcda/synApps/std/epidRecord.html) record, to update the operating power of the heater so that the temperature reaches a desired value.\n",
+    "A _PID_ loop (see below) has been [paired](https://github.com/epics-modules/optics/blob/master/opticsApp/Db/fb_epid.db) with the simulated temperature using the synApps [epid](https://epics.anl.gov/bcda/synApps/std/epidRecord.html) record, to update the operating power of the heater so that the temperature reaches a desired value.\n",
     "\n",
-    "Significant _additional_ **realism is added to the simulation** by switching to the synApps [`transform`](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/transformRecord.html) record.  The `transform` record also has 16 fields for values plus additional features:\n",
+    "Significant _additional_ **realism is added to the simulation** by switching to the synApps [transform](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/transformRecord.html) record.  The `transform` record also has 16 fields for values plus additional features:\n",
     "\n",
     "- value (same as `swait` record)\n",
     "- (optional) input PV link (same as `swait` record)\n",
@@ -82,7 +82,7 @@
     "\n",
     "Certain fields of this `transform` record are linked to fields in an `epid` record.  When the `transform` record is [evaluated](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html) (_processed_, in EPICS terms), the `epid` is then _processed_.  The `epid` record computes a new value (of _power_fraction_, the fraction of total heater power) for the next computation of the temperature signal.\n",
     "\n",
-    "The simulated temperature is re-computed (processed) [periodically](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#scanning-specification), as configured by the `transform` record's [`.SCAN`](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html?highlight=.SCAN#periodic-scanning) field.\n",
+    "The simulated temperature is re-computed (processed) [periodically](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#scanning-specification), as configured by the `transform` record's [.SCAN](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html?highlight=.SCAN#periodic-scanning) field.\n",
     "When `transform` is processed, it first pulls the _power_fraction_ from `epid` (the output of the PID loop calculation) for the next simulated temperature.\n",
     "\n",
     "Once `transform` processing is complete, the `epid` record is told to process itself by configuring the `transform` record's [forward link](https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#forward-links) (.`FLNK`) field.  The _setpoint_ is pushed from `transform` to `epid`_ while `epid` pulls the current _temperature_ (readback) from `transform`.\n",
@@ -106,12 +106,12 @@
    "source": [
     "## ophyd interface\n",
     "\n",
-    "This notebook will configure both `transform` and `epid` records using `ophyd` Python tools within the [Bluesky](https://blueskyproject.io/) framework.  GUI screens from the [`caQtDM`](https://caqtdm.github.io/) application will show the summary settings of each record.\n",
+    "This notebook will configure both `transform` and `epid` records using `ophyd` Python tools within the [Bluesky](https://blueskyproject.io/) framework.  GUI screens from the [caQtDM](https://caqtdm.github.io/) application will show the summary settings of each record.\n",
     "\n",
     "record | EPICS PV | Python object | ophyd support\n",
     "--- | --- | --- | ---\n",
-    "`transform` | `\"gp:userTran1\"` | `heater` | [`apstools.synApps.TransformRecord`](https://bcda-aps.github.io/apstools/latest/api/synApps/_transform.html)\n",
-    "`epid` | `\"gp:epid1\"` | `pid` | [`apstools.synApps.EpidRecord`](https://bcda-aps.github.io/apstools/latest/api/synApps/_epid.html)"
+    "`transform` | `\"gp:userTran1\"` | `heater` | [apstools.synApps.TransformRecord](https://bcda-aps.github.io/apstools/latest/api/synApps/_transform.html)\n",
+    "`epid` | `\"gp:epid1\"` | `pid` | [apstools.synApps.EpidRecord](https://bcda-aps.github.io/apstools/latest/api/synApps/_epid.html)"
    ]
   },
   {
diff --git a/docs/source/howto/_custom_plan.ipynb b/docs/source/howto/_custom_plan.ipynb
index 60d4094d..57ebb168 100644
--- a/docs/source/howto/_custom_plan.ipynb
+++ b/docs/source/howto/_custom_plan.ipynb
@@ -543,7 +543,7 @@
     "\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. Control the `shutter` (hint: `yield from bps.mv(shutter, \"open\")` or `close`)\n",
     "1. Change the temperature before *up* scan and then before *down* scan.  (hint: `yield from bps.mv(temperature, value)`)"
diff --git a/docs/source/howto/_dynamic_limits_2motor.ipynb b/docs/source/howto/_dynamic_limits_2motor.ipynb
index ac6d806f..27c4ccd6 100644
--- a/docs/source/howto/_dynamic_limits_2motor.ipynb
+++ b/docs/source/howto/_dynamic_limits_2motor.ipynb
@@ -21,7 +21,7 @@
     "\n",
     "To prevent the collision *in this case*, the $2\\theta$ axis must be at least $\\delta$ degrees above the $\\theta$ axis.  Empirically, $\\delta$ of 3 degrees is sufficient protection.\n",
     "\n",
-    "From a controls safety view, we provide an EPICS PV calculation that is zero when the move is not permitted and one when: ($2\\theta - \\theta) \\ge \\delta$.  We'll monitor that PV in Bluesky to add a [suspender](https://blueskyproject.io/bluesky/state-machine.html#automated-suspension) that can interrupt the scan (via the [`bluesky.RunEngine`](https://blueskyproject.io/bluesky/run_engine_api.html?highlight=runengine)) if the permit is removed.  When the RunEngine handles an interruption involving [*movable devices*](https://blueskyproject.io/bluesky/hardware.html?highlight=movables#settable-movable-device), it sends a stop to each of the movables involved.  Thus, when the dynamic limit permit is removed, both motors are stopped and the scan pauses, waiting for external interaction to clear the condition.\n",
+    "From a controls safety view, we provide an EPICS PV calculation that is zero when the move is not permitted and one when: ($2\\theta - \\theta) \\ge \\delta$.  We'll monitor that PV in Bluesky to add a [suspender](https://blueskyproject.io/bluesky/state-machine.html#automated-suspension) that can interrupt the scan (via the [bluesky.RunEngine](https://blueskyproject.io/bluesky/run_engine_api.html?highlight=runengine)) if the permit is removed.  When the RunEngine handles an interruption involving [*movable devices*](https://blueskyproject.io/bluesky/hardware.html?highlight=movables#settable-movable-device), it sends a stop to each of the movables involved.  Thus, when the dynamic limit permit is removed, both motors are stopped and the scan pauses, waiting for external interaction to clear the condition.\n",
     "\n",
     "<details>\n",
     "[Here](https://github.com/bluesky/bluesky/blob/4fab894bddbd4a563f28852ea3171b87140ae7b9/bluesky/run_engine.py#L1034-L1036) is where bluesky tells the motors to stop:\n",
@@ -67,7 +67,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We start with two motor axes defined in EPICS.  Here, we run the docker image [`prjemian/synApps`](https://hub.docker.com/r/prjemian/synapps) to make the [EPICS IOC simulator run in a docker container](https://github.com/prjemian/epics-docker/#custom-synappshttps://github.com/prjemian/epics-docker/#custom-synapps) with IOC prefix `gp:`.  These are motor PVs: `gp:m1` and `gp:m2` as shown.\n",
+    "We start with two motor axes defined in EPICS.  Here, we run the docker image [prjemian/synApps](https://hub.docker.com/r/prjemian/synapps) to make the [EPICS IOC simulator run in a docker container](https://github.com/prjemian/epics-docker/#custom-synappshttps://github.com/prjemian/epics-docker/#custom-synapps) with IOC prefix `gp:`.  These are motor PVs: `gp:m1` and `gp:m2` as shown.\n",
     "\n",
     "![EPICS motor GUI screens](/_static/demo_dynamic_limits_motors.png)"
    ]
diff --git a/docs/source/howto/_images_darks_flats.ipynb b/docs/source/howto/_images_darks_flats.ipynb
index 5a6817a0..06a91c3e 100644
--- a/docs/source/howto/_images_darks_flats.ipynb
+++ b/docs/source/howto/_images_darks_flats.ipynb
@@ -41,7 +41,7 @@
     "(`$(P):cam1:FrameType` and `$(P):cam1:FrameType_RBV`).\n",
     "\n",
     "In NeXus, detector data is stored within the\n",
-    "[`instrument`](https://manual.nexusformat.org/classes/base_classes/NXinstrument.html#nxinstrument-detector-group)\n",
+    "[instrument](https://manual.nexusformat.org/classes/base_classes/NXinstrument.html#nxinstrument-detector-group)\n",
     "group, traditionally at `/entry/instrument/detector/`.  We then hard link the\n",
     "field `data`, `dark`, and `white` fields to the `/entry/data/` group.  The hard\n",
     "links provide a shorter HDF5 address.  We use this shorter address in EPICS, to\n",
diff --git a/docs/source/howto/_synapps_sscan_1d_flyer.ipynb b/docs/source/howto/_synapps_sscan_1d_flyer.ipynb
index 4dba613f..b9b7d539 100644
--- a/docs/source/howto/_synapps_sscan_1d_flyer.ipynb
+++ b/docs/source/howto/_synapps_sscan_1d_flyer.ipynb
@@ -39,7 +39,7 @@
     "\n",
     "Suggest the _noisy *v* m1_ scan, done as 1-D step scan with `sscan` record, where `noisy` is the [*swait*](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/swaitRecord.html) record calculating a Lorentzian peak based on `m1` (EPICS [*motor*]([*swait*](https://epics.anl.gov/bcda/synApps/motor/motorRecord.html)) record) position.\n",
     "\n",
-    "We'll build a custom Python class, from [`apstools.synApps.SscanRecord`](https://apstools.readthedocs.io/en/latest/source/synApps/_sscan.html) (a subclass of [`ophyd.Device`](https://blueskyproject.io/ophyd/tutorials/device.html#define-a-custom-device)), that supports the EPICS [*sscan*](https://epics.anl.gov/bcda/synApps/sscan/sscanRecord.html) record and add the [`ophyd.FlyerInterface`](https://blueskyproject.io/ophyd/architecture.html#fly-able-interface) to that class.  A class method will configure the Device staging to setup the sscan record for a 1-D step scan using the [`m1`](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/motors.py#L25) positioner and the [`noisy`](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L42) detector.  `noisy` is implemented as an EPICS [*swait*](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/swaitRecord.html) record configured to recalculate a Lorentzian profile when the `m1` readback value changes.  The center, width, and height are [set randomly](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L24-L38) as this bluesky instrument package is loaded.  The center of the simulated peak will be defined somewhere between [+/- 1](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L34)."
+    "We'll build a custom Python class, from [apstools.synApps.SscanRecord](https://apstools.readthedocs.io/en/latest/source/synApps/_sscan.html) (a subclass of [ophyd.Device](https://blueskyproject.io/ophyd/tutorials/device.html#define-a-custom-device)), that supports the EPICS [*sscan*](https://epics.anl.gov/bcda/synApps/sscan/sscanRecord.html) record and add the [ophyd.FlyerInterface](https://blueskyproject.io/ophyd/architecture.html#fly-able-interface) to that class.  A class method will configure the Device staging to setup the sscan record for a 1-D step scan using the [m1](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/motors.py#L25) positioner and the [noisy](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L42) detector.  `noisy` is implemented as an EPICS [*swait*](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/calc/R3-6-1/documentation/swaitRecord.html) record configured to recalculate a Lorentzian profile when the `m1` readback value changes.  The center, width, and height are [set randomly](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L24-L38) as this bluesky instrument package is loaded.  The center of the simulated peak will be defined somewhere between [+/- 1](https://github.com/BCDA-APS/bluesky_training/blob/711baca0e4fcdffc97fb4d05ee73d4b5b93fcc3a/bluesky/instrument/devices/noisy_detector.py#L34)."
    ]
   },
   {
diff --git a/docs/source/instrument/_configure_bluesky_instrument.md b/docs/source/instrument/_configure_bluesky_instrument.md
index 6151335c..54925e03 100644
--- a/docs/source/instrument/_configure_bluesky_instrument.md
+++ b/docs/source/instrument/_configure_bluesky_instrument.md
@@ -92,7 +92,7 @@ NeXus files using a
 [callback](https://github.com/APS-USAXS/usaxs-bluesky/blob/master/instrument/callbacks/nxwriter.py).
 
 The order of file loading is controlled by the lines in the
-[`__init__.py`](./_about_init_files.md) file.  In some cases, the sequence of
+[__init__.py](./_about_init_files.md) file.  In some cases, the sequence of
 loading is important.
 
 ### Devices
@@ -109,7 +109,7 @@ hardware. These files are leftovers as used in the bluesky training examples and
 provide ideas for what is possible with your instrument.
 
 The order of file loading is controlled by the lines in the
-[`__init__.py`](./_about_init_files.md) file.  In some cases, the sequence of
+[__init__.py](./_about_init_files.md) file.  In some cases, the sequence of
 loading is important.
 
 **Note**: A major principle is that any activities on startup **should not
@@ -118,7 +118,7 @@ EPICS will not be affected just beacuse a Bluesky session was started.
 (This is why you changed `ALLOW_AREA_DETECTOR_WARMUP` to `false` above.)
 
 **Tip**: SPEC users:
-[`spec2ophyd`](https://bcda-aps.github.io/apstools/latest/applications/spec2ophyd.html#spec2ophyd)
+[spec2ophyd](https://bcda-aps.github.io/apstools/latest/applications/spec2ophyd.html#spec2ophyd)
 can translate much of your SPEC config file into content for the Devices
 directory.
 
@@ -128,7 +128,7 @@ The `instrument/plans/` directory contains Python files that define the custom
 Bluesky plans for your instrument.  The existing files serve as examples.
 
 The order of file loading is controlled by the lines in the
-[`__init__.py`](./_about_init_files.md) file.  In some cases, the sequence of
+[__init__.py](./_about_init_files.md) file.  In some cases, the sequence of
 loading is important.
 
 ### Utils
@@ -138,5 +138,5 @@ classified as Callbacks, Devices, or Plans.  For example, standard analytical
 routines might be best placed in Utils.
 
 The order of file loading is controlled by the lines in the
-[`__init__.py`](./_about_init_files.md) file.  In some cases, the sequence of
+[__init__.py](./_about_init_files.md) file.  In some cases, the sequence of
 loading is important.
diff --git a/docs/source/instrument/_configure_databroker.md b/docs/source/instrument/_configure_databroker.md
index bc263468..bbba35e9 100644
--- a/docs/source/instrument/_configure_databroker.md
+++ b/docs/source/instrument/_configure_databroker.md
@@ -5,7 +5,7 @@ with some location where data is stored, typically a MongoDB collection.
 This is called a catalog configuration file.
 
 The catalog configuration file must be placed in a directory where
-[`databroker`](https://blueskyproject.io/databroker/how-to/mongo-backed-catalog.html)
+[databroker](https://blueskyproject.io/databroker/how-to/mongo-backed-catalog.html)
 expects to find it.  Run this snippet to find the list of paths where it looks on your system:
 
 <pre>
diff --git a/docs/source/instrument/_get_spec_config.md b/docs/source/instrument/_get_spec_config.md
index bd601b56..0411e30c 100644
--- a/docs/source/instrument/_get_spec_config.md
+++ b/docs/source/instrument/_get_spec_config.md
@@ -1,6 +1,6 @@
 # Translate Previous SPEC Configuration
 
-The [`apstools`](https://bcda-aps.github.io/apstools/latest/) package has an application that will translate most
+The [apstools](https://bcda-aps.github.io/apstools/latest/) package has an application that will translate most
 of the SPEC config file into ophyd commands.  The output is to the
 console.  Use a pipe to direct the output to a new file:
 
diff --git a/docs/source/instrument/bluesky_class.yml b/docs/source/instrument/bluesky_class.yml
new file mode 100644
index 00000000..67eb968a
--- /dev/null
+++ b/docs/source/instrument/bluesky_class.yml
@@ -0,0 +1,13 @@
+# file: bluesky_class.yml
+# purpose: Configuration file to connect Bluesky databroker with MongoDB
+# For 2021-03 Python Training at APS
+
+# Copy to: ~/.local/share/intake/bluesky_class.yml
+# Create subdirectories as needed
+
+sources:
+  class_2021_03:
+    args:
+      asset_registry_db: mongodb://localhost:27017/class_2021_03-bluesky
+      metadatastore_db: mongodb://localhost:27017/class_2021_03-bluesky
+    driver: bluesky-mongo-normalized-catalog
diff --git a/docs/source/instrument/describe_instrument.ipynb b/docs/source/instrument/describe_instrument.ipynb
index 0cac8df9..6b095114 100644
--- a/docs/source/instrument/describe_instrument.ipynb
+++ b/docs/source/instrument/describe_instrument.ipynb
@@ -33,8 +33,8 @@
     "\n",
     "prefix | description | docker image | documentation\n",
     ":--- | :--- | :--- | :---\n",
-    "`ad:` | area detector IOC | [`prjemian/custom-synapps-6.2-ad-3.10`](https://hub.docker.com/r/prjemian/custom-synapps-6.2-ad-3.10) | https://github.com/prjemian/epics-docker/tree/main/v1.1/n6_custom_areaDetector\n",
-    "`gp:` | general purpose IOC | [`prjemian/prjemian/custom-synapps-6.2`](https://hub.docker.com/r/prjemian/custom-synapps-6.2) | https://github.com/prjemian/epics-docker/tree/main/v1.1/n5_custom_synApps\n",
+    "`ad:` | area detector IOC | [prjemian/custom-synapps-6.2-ad-3.10](https://hub.docker.com/r/prjemian/custom-synapps-6.2-ad-3.10) | https://github.com/prjemian/epics-docker/tree/main/v1.1/n6_custom_areaDetector\n",
+    "`gp:` | general purpose IOC | [prjemian/prjemian/custom-synapps-6.2](https://hub.docker.com/r/prjemian/custom-synapps-6.2) | https://github.com/prjemian/epics-docker/tree/main/v1.1/n5_custom_synApps\n",
     "\n",
     "</details>"
    ]
@@ -193,7 +193,7 @@
    "id": "ff54948c",
    "metadata": {},
    "source": [
-    "The EPICS Area Detector ADSimDetector is included with this instrument as `adsimdet`.  The detector is a monochrome 1k x 1k frame.  The image is written to an HDF5 file and made available to the [`databroker`](#databroker) via a shared volume from the docker container.  `adsimdet` can be used as a detector.\n",
+    "The EPICS Area Detector ADSimDetector is included with this instrument as `adsimdet`.  The detector is a monochrome 1k x 1k frame.  The image is written to an HDF5 file and made available to the [databroker](#databroker) via a shared volume from the docker container.  `adsimdet` can be used as a detector.\n",
     "\n",
     "The image is a simulated diffraction spot with center randomly-chosen between 100..900 on both axes.  The width is also random as is the peak intensity and noise level.  Furthermore, to simulate realistic conditions, the center position of both axes is adjusted by a few pixels using a pair of *swait* records (`gp:userCalc9` & `gp:userCalc10`) updating from random numbers."
    ]
@@ -733,7 +733,7 @@
    "source": [
     "There are 16 soft motor channels: `gp:m1` .. `gp:m16`.  Any motor can be used as a detector **and** as a positioner.\n",
     "\n",
-    "The first motor, `gp:m1`, is used to compute a simulated 1-D diffraction peak ([`noisy`](#noisy)) using `gp:userCalc1`.\n",
+    "The first motor, `gp:m1`, is used to compute a simulated 1-D diffraction peak ([noisy](#noisy)) using `gp:userCalc1`.\n",
     "\n",
     "To make it easier to change the motor step size, a custom `MyEpicsMotor` class was made, subclassing from `ophyd.EpicsMotor` and adding a component to access the motor's `.SREV` (steps/revolution) field.  The default motor step size is 0.01 (with SREV=200).  For only `m1`, the step size has been changed to 0.001 by setting SREV=2000.\n",
     "\n",
@@ -1032,7 +1032,7 @@
    "source": [
     "## SPEC data files\n",
     "\n",
-    "A [SPEC](https://certif.com) data file records a copy of the scan data (area detector images are not stored in SPEC files).  By default, the file is created in the present working directory using a name constructed from the date and time with a `.dat` file extension.  Unlike SPEC, new data is written *at the end of a scan*.  It is also possible to use the [`SpecWriterCallback`](https://apstools.readthedocs.io/en/latest/source/_filewriters.html#apstools.filewriters.SpecWriterCallback) to write data extracted from the database after the experiment is done.\n",
+    "A [SPEC](https://certif.com) data file records a copy of the scan data (area detector images are not stored in SPEC files).  By default, the file is created in the present working directory using a name constructed from the date and time with a `.dat` file extension.  Unlike SPEC, new data is written *at the end of a scan*.  It is also possible to use the [SpecWriterCallback](https://apstools.readthedocs.io/en/latest/source/_filewriters.html#apstools.filewriters.SpecWriterCallback) to write data extracted from the database after the experiment is done.\n",
     "\n",
     "The 2021-03 training does not cover the use of these files.  You are free to examine them yourselves.\n",
     "\n",
@@ -1222,7 +1222,7 @@
     "\n",
     "A common request from instruments is to allow the user to write some python code that can be loaded into the current session.  Since development of this *user code* is often iterative, it must be possible to reload the code without requiring the session to exit and restart.\n",
     "\n",
-    "The local file [`quick_hello.py`](../../../bluesky/user/quick_hello.py) provides an example of such a user code file.  Load this file with the command:\n",
+    "The local file `user/quick_hello.py` provides an example of such a user code file.  Load this file with the command:\n",
     "\n",
     "    %run -im user.quick_hello\n",
     "\n",
@@ -1230,7 +1230,7 @@
     "\n",
     "The `%run` is an [IPython Magic](https://ipython.readthedocs.io/en/stable/interactive/magics.html) command.  _Magic_ commands are only available from the _interactive_ IPython command line (either in a console or Jupyter notebook).  You can't use them in your Python files, functions, classes, etc.\n",
     "\n",
-    "The `user/` directory must be on the import path, which we did as part of starting the `instrument` package (above).  Also, `user/` _must_ contain a file named [`__init__.py`](./_about_init_files.md) so that `user` is an importable Python package.\n",
+    "The `user/` directory must be on the import path, which we did as part of starting the `instrument` package (above).  Also, `user/` _must_ contain a file named [__init__.py](./_about_init_files.md) so that `user` is an importable Python package.\n",
     "\n",
     "The `m` (as module) command option was added so it is not necessary to give the Python extension `.py`.\n",
     "\n",
@@ -1308,12 +1308,12 @@
    "source": [
     "## databroker\n",
     "\n",
-    "The [`databroker`](https://blueskyproject.io/databroker) package provides \n",
+    "The [databroker](https://blueskyproject.io/databroker) package provides \n",
     "a Python interface to the database with the experiment data, including \n",
     "references to the large file content such as area detector images.  A \n",
     "[YAML](https://yaml.org) configuration file connects databroker with a \n",
     "specific repository in the MongoDB database server.  In the example here \n",
-    "([`bluesky_class.yml`](./bluesky_class.yml)), the name of the *catalog* entry\n",
+    "([bluesky_class.yml](./bluesky_class.yml)), the name of the *catalog* entry\n",
     "in this file is `class_2021_03`.  It makes two connections to a MongoDB server\n",
     "running on the same workstation `localhost`.  Both connections are to the \n",
     "same MongoDB collection: `class_2021_03-bluesky`.  The name of the file\n",
@@ -1369,7 +1369,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.11"
+   "version": "3.10.4"
   }
  },
  "nbformat": 4,
diff --git a/docs/source/instrument/guide.md b/docs/source/instrument/guide.md
index b5b7deb4..3aa7da6f 100644
--- a/docs/source/instrument/guide.md
+++ b/docs/source/instrument/guide.md
@@ -30,13 +30,13 @@ instrument/       <-- all aspects of the equipment
     iconfig.yml   <-- instrument configuration settings for you to customize
 ```
 
-Each directory has a [`__init__.py`](./_about_init_files.md) file (which _can_ be empty).  The very
+Each directory has a [__init__.py](./_about_init_files.md) file (which _can_ be empty).  The very
 existence of this file informs Python that the directory is a Python *package*
 which means that it can be imported.  The `__init__.py` file can be used to control
 what is imported and the order in which that import is sequenced.
 
 In any of the Python files, the
-[`__all__`](https://stackoverflow.com/questions/44834) symbol is a Python list
+[__all__](https://stackoverflow.com/questions/44834) symbol is a Python list
 that identifies which Python symbols from that file will be imported by default.
 (Any Python symbol may be imported by name, this just controls the more general
 case.)
@@ -70,13 +70,13 @@ convention, the `name=` keyword has the same value as the LHS.  The keyword
 [tuple](https://docs.python.org/3/library/stdtypes.html?highlight=tuple#sequence-types-list-tuple-range).
 When the `motor` value is added to the tuple, then this motor will show up in
 the report provided by the
-[`%wa`](https://blueskyproject.io/bluesky/magics.html?highlight=magic#listing-available-motors-using-wa-post-v1-3-0)
+[%wa](https://blueskyproject.io/bluesky/magics.html?highlight=magic#listing-available-motors-using-wa-post-v1-3-0)
 (bluesky IPython) magic command.
 
 CAUTION: Avoid certain names such as
-[`del`](https://docs.python.org/3/reference/simple_stmts.html?highlight=del#the-del-statement)
+[del](https://docs.python.org/3/reference/simple_stmts.html?highlight=del#the-del-statement)
 and
-[`lambda`](https://docs.python.org/3/reference/expressions.html?highlight=lambda#lambda)
+[lambda](https://docs.python.org/3/reference/expressions.html?highlight=lambda#lambda)
 since these are reserved Python names with very important meanings.  
 
 Be sure to add this new motor symbol to the `__all__` list near the top of the file.
@@ -270,8 +270,8 @@ Sometimes, a user may need experiment-specific code that is not for general
 inclusion in the instrument package.  Components from the `instrument` package
 may be imported from such custom user code by writing a file in the working
 directory with the support.  The file can be loaded and run in an IPython
-session with the [`%run -i
-filename.py`](https://ipython.org/ipython-doc/3/interactive/magics.html#magic-run)
+session with the [%run -i
+filename.py](https://ipython.org/ipython-doc/3/interactive/magics.html#magic-run)
 magic command.
 
 <details>
diff --git a/docs/source/tutor/_aps101_notes.md b/docs/source/tutor/_aps101_notes.md
index cdd4cc77..dbaad055 100644
--- a/docs/source/tutor/_aps101_notes.md
+++ b/docs/source/tutor/_aps101_notes.md
@@ -82,9 +82,9 @@ graphical text editors, MongoDB database server, and Python infrastructure.
 - Are there other tutorials available online?  [Yes!](https://blueskyproject.io/tutorials/README.html)
 - [How to access data from previous measurements?](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/after_measurement.ipynb)
 - [How to plot data from previous scans?](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/plot_x_y_databroker.ipynb)
-- How to use [EPICS area detectors](https://areadetector.github.io)? ([setup](https://apstools.readthedocs.io/en/latest/examples/_ad__pilatus.html), [measure](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/locate_image_peak.ipynb), [analyze from `databroker`](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/bluesky/databroker_analysis.ipynb))
+- How to use [EPICS area detectors](https://areadetector.github.io)? ([setup](https://apstools.readthedocs.io/en/latest/examples/_ad__pilatus.html), [measure](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/locate_image_peak.ipynb), [analyze from databroker](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/bluesky/databroker_analysis.ipynb))
 - How to support complex [devices](https://blueskyproject.io/ophyd/tutorials/device.html?highlight=device)?
-- How does [`databroker`](https://blueskyproject.io/databroker/) store the data?
+- How does [databroker](https://blueskyproject.io/databroker/) store the data?
 - What is [MongoDB](https://www.mongodb.com/)?
 - [How to execute Linux command from Bluesky?](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/demo_doodle.ipynb)
 - [How to setup and use a diffractometer with Bluesky?](https://blueskyproject.io/hklpy/examples/index.html)
@@ -107,5 +107,5 @@ Links to the videos from the training sessions of 2021 August and September are
 - [References from Bluesky Tutorials](https://blueskyproject.io/tutorials/README.html#references)
 - [Jupyter Lab](https://jupyterlab.readthedocs.io)
 - [EPICS](https://epics-controls.org/) ([old web site](https://epics.anl.gov/))
-- [More on `EpicsSignal`](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/connect_epics.ipynb) including `ophyd.Device`
+- [More on EpicsSignal](https://nbviewer.jupyter.org/github/BCDA-APS/bluesky_training/blob/main/connect_epics.ipynb) including `ophyd.Device`
 - For more about Juypter, see the Bluesky [Hello Python and Jupyter](https://blueskyproject.io/tutorials/Hello%20Python%20and%20Jupyter.html) Tutorial.
diff --git a/docs/source/tutor/_basic_a.ipynb b/docs/source/tutor/_basic_a.ipynb
index bd9f0349..f51289c8 100644
--- a/docs/source/tutor/_basic_a.ipynb
+++ b/docs/source/tutor/_basic_a.ipynb
@@ -270,7 +270,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`scaler.preset_time` is an [`EpicsSignal`](https://github.com/bluesky/ophyd/blob/7612b2c9de9d5bc16cf28eea79ba5c12553f3cc2/ophyd/signal.py#L1615).  All such [Signal](https://blueskyproject.io/ophyd/signals.html) objects have a `.get()` method which returns the Signal's value."
+    "`scaler.preset_time` is an [EpicsSignal](https://github.com/bluesky/ophyd/blob/7612b2c9de9d5bc16cf28eea79ba5c12553f3cc2/ophyd/signal.py#L1615).  All such [Signal](https://blueskyproject.io/ophyd/signals.html) objects have a `.get()` method which returns the Signal's value."
    ]
   },
   {
@@ -388,7 +388,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we'll load a library with many [predefined plans](https://blueskyproject.io/bluesky/plans.html#summary).  The first plan we want to use is [`count()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  By the way, we'll use a python feature to rename `bluesky.plans` to the shorter `bp` since it will be used a lot."
+    "Next, we'll load a library with many [predefined plans](https://blueskyproject.io/bluesky/plans.html#summary).  The first plan we want to use is [count()](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  By the way, we'll use a python feature to rename `bluesky.plans` to the shorter `bp` since it will be used a lot."
    ]
   },
   {
diff --git a/docs/source/tutor/_command_review.ipynb b/docs/source/tutor/_command_review.ipynb
index d94d72b4..64b13c0a 100644
--- a/docs/source/tutor/_command_review.ipynb
+++ b/docs/source/tutor/_command_review.ipynb
@@ -252,7 +252,7 @@
    "id": "f47d2f44",
    "metadata": {},
    "source": [
-    "Might be a good idea to know now what ophyd symbols are available.  The [apstools](https://bcda-aps.github.io/apstools/latest/) package provides a [`listobjects()`](https://bcda-aps.github.io/apstools/latest/api/_utils.html#apstools.utils.misc.listobjects) command that prints a table of all the known objects (in the global namespace of the session).  The columns provide the ophyd name (the name you use to call this in Python), the name of the ophyd structure, the EPICS PV (if relevant), and any labels (as used in `%wa` above)."
+    "Might be a good idea to know now what ophyd symbols are available.  The [apstools](https://bcda-aps.github.io/apstools/latest/) package provides a [listobjects()](https://bcda-aps.github.io/apstools/latest/api/_utils.html#apstools.utils.misc.listobjects) command that prints a table of all the known objects (in the global namespace of the session).  The columns provide the ophyd name (the name you use to call this in Python), the name of the ophyd structure, the EPICS PV (if relevant), and any labels (as used in `%wa` above)."
    ]
   },
   {
diff --git a/docs/source/tutor/_lesson1.ipynb b/docs/source/tutor/_lesson1.ipynb
index c9c5392e..3c4ababa 100644
--- a/docs/source/tutor/_lesson1.ipynb
+++ b/docs/source/tutor/_lesson1.ipynb
@@ -12,7 +12,7 @@
     "First, we'll show how to start a Jupyter notebook.  Next, we'll connect with an EPICS scaler (using [ophyd](https://blueskyproject.io/ophyd/)), and then use the Bluesky software to count from the scaler.\n",
     "\n",
     "\n",
-    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [`xxx`](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md\n",
+    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [xxx](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md\n",
     "\n",
     "\n",
     "## Starting this session in a Jupyter notebook\n",
@@ -53,7 +53,7 @@
     "\n",
     "I have a synApps (v6.1) *XXX*-style IOC with the prefix `sky:`.  It has a [scaler](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/std/R3-4-1/documentation/scalerRecord.html), 16 soft channel [motor](https://github.com/epics-modules/motor)s, and some other support we'll ignore in lesson 1.\n",
     "\n",
-    "The scaler is `sky:scaler1`.  We'll connect to that first.  To make the connection, we need to import the [`ScalerCH`](https://blueskyproject.io/ophyd/builtin-devices.html#epicsscaler) device from the [`ophyd.scaler`](https://blueskyproject.io/ophyd/) library."
+    "The scaler is `sky:scaler1`.  We'll connect to that first.  To make the connection, we need to import the [ScalerCH](https://blueskyproject.io/ophyd/builtin-devices.html#epicsscaler) device from the [ophyd.scaler](https://blueskyproject.io/ophyd/) library."
    ]
   },
   {
@@ -120,7 +120,7 @@
    "source": [
     "By default, the ophyd `ScalerCH` object shows data for only the channels with names defined in EPICS.  Except for one channel (probably a bug in the `ScalerCH` code).  To fix that, we'll load another support library.  (Loading additional support as we need it will be a common theme in these lessons.  Rather than loading all the libraries first, as is common in python code files, we'll load support code as the need arises.)\n",
     "\n",
-    "The new support code is `use_EPICS_scaler_channels` from [`apstools.devices`](https://bcda-aps.github.io/apstools/latest/api/_devices.html#apstools.devices.scaler_support.use_EPICS_scaler_channels)."
+    "The new support code is `use_EPICS_scaler_channels` from [apstools.devices](https://bcda-aps.github.io/apstools/latest/api/_devices.html#apstools.devices.scaler_support.use_EPICS_scaler_channels)."
    ]
   },
   {
@@ -198,7 +198,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Since `scaler.preset_time` is an [`EpicsSignal`](https://github.com/NSLS-II/ophyd/blob/master/ophyd/signal.py#L647), ([Signal](https://blueskyproject.io/ophyd/signals.html) is a fundamental ophyd structure), we print its `.value`."
+    "Since `scaler.preset_time` is an [EpicsSignal](https://github.com/NSLS-II/ophyd/blob/master/ophyd/signal.py#L647), ([Signal](https://blueskyproject.io/ophyd/signals.html) is a fundamental ophyd structure), we print its `.value`."
    ]
   },
   {
@@ -283,7 +283,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we'll load a library with many [predefined plans](https://blueskyproject.io/bluesky/plans.html#summary).  The first plan we want to use is [`count()`](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  By the way, we'll use a python feature to rename `bluesky.plans` to the shorter `bp` since it will be used a lot."
+    "Next, we'll load a library with many [predefined plans](https://blueskyproject.io/bluesky/plans.html#summary).  The first plan we want to use is [count()](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  By the way, we'll use a python feature to rename `bluesky.plans` to the shorter `bp` since it will be used a lot."
    ]
   },
   {
diff --git a/docs/source/tutor/_lesson2.ipynb b/docs/source/tutor/_lesson2.ipynb
index 0117eaaf..0b6d7554 100644
--- a/docs/source/tutor/_lesson2.ipynb
+++ b/docs/source/tutor/_lesson2.ipynb
@@ -13,7 +13,7 @@
     "\n",
     "Load `ophyd` device support for the `EpicsMotor` and connect with one EPICS motor channel.  We have a synApps (v6.1) XXX-style IOC with the prefix `sky:`. It has a scaler, 16 soft channel motors, and some other support we'll ignore in this lesson.\n",
     "\n",
-    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [`xxx`](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md"
+    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [xxx](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md"
    ]
   },
   {
diff --git a/docs/source/tutor/_lesson3a.ipynb b/docs/source/tutor/_lesson3a.ipynb
index 8fb4b384..522dd39d 100644
--- a/docs/source/tutor/_lesson3a.ipynb
+++ b/docs/source/tutor/_lesson3a.ipynb
@@ -13,7 +13,7 @@
     "\n",
     "-------\n",
     "\n",
-    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [`xxx`](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md\n",
+    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [xxx](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md\n",
     "\n",
     "Starting with the configuration from lessons 1 and 2, we first group the `import`s together as is common Python practice:"
    ]
diff --git a/docs/source/tutor/_lesson3b.ipynb b/docs/source/tutor/_lesson3b.ipynb
index 7a1163bf..3475ff77 100644
--- a/docs/source/tutor/_lesson3b.ipynb
+++ b/docs/source/tutor/_lesson3b.ipynb
@@ -9,7 +9,7 @@
     "\n",
     "[Lesson 3](https://bcda-aps.github.io/bluesky_training/tutor/_lesson3a.html) demonstrated how bluesky can show data as it is acquired.  This notebook provides a concise summary, which should be a good general starting point for users.\n",
     "\n",
-    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [`xxx`](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md"
+    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [xxx](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md"
    ]
   },
   {
diff --git a/docs/source/tutor/_lesson5a.ipynb b/docs/source/tutor/_lesson5a.ipynb
index 0e5e85d7..7e9a068d 100644
--- a/docs/source/tutor/_lesson5a.ipynb
+++ b/docs/source/tutor/_lesson5a.ipynb
@@ -419,7 +419,7 @@
    "source": [
     "We need to tell the detector to acquire data.  To acquire data, our simulator will re-compute its value based on the motor position (as with a real detector, the value does not update without something that compels this computation), since that may have changed since the last computation.\n",
     "\n",
-    "For interactive use with ophyd Devices, the command to call is [`%ct`](https://blueskyproject.io/bluesky/magics.html#taking-a-reading-using-ct-post-v1-3-0).  We labeled the `noisy` object as `detectors` so it will be counted when `%ct` is called.\n",
+    "For interactive use with ophyd Devices, the command to call is [%ct](https://blueskyproject.io/bluesky/magics.html#taking-a-reading-using-ct-post-v1-3-0).  We labeled the `noisy` object as `detectors` so it will be counted when `%ct` is called.\n",
     "\n",
     "TODO: improve the labels explanation here."
    ]
diff --git a/docs/source/tutor/_lesson6.ipynb b/docs/source/tutor/_lesson6.ipynb
index 2eb1ec2a..d6a6fea2 100644
--- a/docs/source/tutor/_lesson6.ipynb
+++ b/docs/source/tutor/_lesson6.ipynb
@@ -43,7 +43,7 @@
     "\n",
     "**note**:  This tutorial expects to find an EPICS IOC \n",
     "on the local network configured as an EPICS AreaDetector \n",
-    "[`ADSimDetector`](https://github.com/areaDetector/ADSimDetector) \n",
+    "[ADSimDetector](https://github.com/areaDetector/ADSimDetector) \n",
     "IOC with prefix `adsky:`.  A docker container is available \n",
     "to provide this IOC.  See this URL for instructions:  \n",
     "https://github.com/prjemian/epics-docker/blob/master/n4_areaDetector/README.md\n",
diff --git a/docs/source/tutor/_lesson7.ipynb b/docs/source/tutor/_lesson7.ipynb
index f7fffae9..c0a5252e 100644
--- a/docs/source/tutor/_lesson7.ipynb
+++ b/docs/source/tutor/_lesson7.ipynb
@@ -107,7 +107,7 @@
    "source": [
     "Next, import the desired diffractometer geometry from the\n",
     "[*hklpy*](https://github.com/bluesky/hklpy) package.  We pick\n",
-    "[`E4CV`](https://people.debian.org/~picca/hkl/hkl.html#orge78e5c4)\n",
+    "[E4CV](https://people.debian.org/~picca/hkl/hkl.html#orge78e5c4)\n",
     "(Eulerian 4-Circle with Vertical scattering geometry)\n",
     "as is typical at synchrotron beamlines."
    ]
@@ -1069,11 +1069,6 @@
     "are presented as a python list which may be empty if there are\n",
     "no solutions.\n",
     "\n",
-    "The [`DiffractometerMixin`](???)   (FIXME: Not in apstools, maybe hklpy?)\n",
-    "provides a helper to print the possible forward solutions for a\n",
-    "list of *hkl* reflections.  (Each reflection is provided as a\n",
-    "python tuple or list.)\n",
-    "\n",
     "Show default solution for a few reflections (*100*), (*010*) and (*001*):"
    ]
   },
@@ -1383,9 +1378,9 @@
    "metadata": {},
    "source": [
     "The value is a\n",
-    "[`Constraint`](???) object.  (FIXME: Not in apstools, maybe hklpy?)\n",
+    "[Constraints](https://blueskyproject.io/hklpy/constraints.html#constraints) object.\n",
     "\n",
-    "`Constraint` Arguments\n",
+    "`Constraints` Arguments\n",
     "\n",
     "* low_limit (*number*) :\n",
     "    Limit solutions for this axis to no less than `low_limit` when `fit=True`.\n",
@@ -1397,8 +1392,7 @@
     "    Calculate with axis = `value` when `fit=False`.\n",
     "\n",
     "* fit (*bool*) :\n",
-    "    When `True`, calculate new values for this axis.\n",
-    "    When `False`, keep this axis fixed at `value`.\n",
+    "    Not used.\n",
     "\n",
     "In the dictionary, it is only necessary to define the axis constraints to be changed.\n",
     "The other (commented out) constraints will not be changed."
diff --git a/docs/source/tutor/connect_epics.ipynb b/docs/source/tutor/connect_epics.ipynb
index 8ce1abbc..b544d7f5 100644
--- a/docs/source/tutor/connect_epics.ipynb
+++ b/docs/source/tutor/connect_epics.ipynb
@@ -19,7 +19,7 @@
    "source": [
     "## Fundamentals\n",
     "\n",
-    "In Bluesky, the [ophyd](https://blueskyproject.io/ophyd) package is used to connect with the underlying control system (EPICS, in this case).  The fundamental structure is the [`EpicsSignal`](https://blueskyproject.io/ophyd/tutorials/single-PV.html#connect-to-a-pv-from-ophyd) which connects a single EPICS Process Variable (PV) with a single python object.  Behind the scenes, the connection is made using the [PyEpics](https://cars9.uchicago.edu/software/python/pyepics3/) package and the EPICS Channel Access protocol.  Other information, when available (such as units, limits, displayed precision, data type, enumeration labels), is obtained from EPICS.\n",
+    "In Bluesky, the [ophyd](https://blueskyproject.io/ophyd) package is used to connect with the underlying control system (EPICS, in this case).  The fundamental structure is the [EpicsSignal](https://blueskyproject.io/ophyd/tutorials/single-PV.html#connect-to-a-pv-from-ophyd) which connects a single EPICS Process Variable (PV) with a single python object.  Behind the scenes, the connection is made using the [PyEpics](https://cars9.uchicago.edu/software/python/pyepics3/) package and the EPICS Channel Access protocol.  Other information, when available (such as units, limits, displayed precision, data type, enumeration labels), is obtained from EPICS.\n",
     "\n",
     "ophyd class | description\n",
     "--- | ---\n",

From f0991abc5067736236ae64c087d2a599a772cb86 Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 12:59:25 -0600
Subject: [PATCH 10/11] additional iconfig options from framework (#278)

* MNT #250 enable options as configuration items

* DOC #250

* MNT #250 omission

* MNT #250 new name

* DOC #250 update release notes
---
 CHANGES.rst                                |  7 ++++++-
 bluesky/instrument/framework/initialize.py | 24 +++++++++++-----------
 bluesky/instrument/iconfig.yml             |  8 ++++++--
 3 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index e5f730e4..fde197bc 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -34,11 +34,16 @@ release expected by 2024-03-01
 New Features
 ------------
 
+* Add options to instrument configuration (iconfig.yml):
+
+  * After every run, verify that files were saved, print a confirmation message. 
+  * Debugging and message options.
+
 * Add package(s) to environment:
 
   * ophyd-registry
 
-* Build ``registry`` of all ophyd objects.
+* Build ``oregistry`` of all ophyd objects.
 
 Maintenance
 ------------
diff --git a/bluesky/instrument/framework/initialize.py b/bluesky/instrument/framework/initialize.py
index 49fdb551..caff6a4b 100644
--- a/bluesky/instrument/framework/initialize.py
+++ b/bluesky/instrument/framework/initialize.py
@@ -1,5 +1,5 @@
 """
-initialize the bluesky framework
+Initialize the bluesky framework.
 """
 
 __all__ = """
@@ -7,8 +7,8 @@
     bp  bps  bpp
     summarize_plan
     np
-    registry
-    """.split()
+    oregistry
+""".split()
 
 import logging
 
@@ -31,7 +31,6 @@
 from bluesky.utils import ProgressBarManager
 from bluesky.utils import ts_msg_hook
 from IPython import get_ipython
-from ophyd.signal import EpicsSignalBase
 from ophydregistry import Registry
 import databroker
 import ophyd
@@ -96,18 +95,19 @@ def get_md_path():
 
 # At the end of every run, verify that files were saved and
 # print a confirmation message.
-# from bluesky.callbacks.broker import verify_files_saved
-# RE.subscribe(post_run(verify_files_saved), 'stop')
+if iconfig.get("VERIFY_FILES_SAVED", False):
+    from bluesky.callbacks.broker import post_run
+    from bluesky.callbacks.broker import verify_files_saved
 
-# Uncomment the following lines to turn on
-# verbose messages for debugging.
-# ophyd.logger.setLevel(logging.DEBUG)
+    RE.subscribe(post_run(verify_files_saved), "stop")
 
+ophyd.logger.setLevel(iconfig.get("LOGGING", {}).get("OPHYD_LOGGER_LEVEL", "WARNING"))
 ophyd.set_cl(iconfig.get("OPHYD_CONTROL_LAYER", "PyEpics").lower())
 logger.info(f"using ophyd control layer: {ophyd.cl.name}")
 
-# diagnostics
-# RE.msg_hook = ts_msg_hook
+if iconfig.get("ADD_DIAGNOSTIC_MESSAGES", False):
+    # Log bluesky Message objects in RunEngine (follow plan's progress).
+    RE.msg_hook = ts_msg_hook
 
 if iconfig.get("RUN_ENGINE_SCAN_ID_PV") is not None:
     from ..epics_signal_config import epics_scan_id_source
@@ -119,4 +119,4 @@ def get_md_path():
     RE.md["scan_id"] = scan_id_epics.get()
 
 # Create a registry of ophyd devices
-registry = Registry(auto_register=True)
+oregistry = Registry(auto_register=True)
diff --git a/bluesky/instrument/iconfig.yml b/bluesky/instrument/iconfig.yml
index 79a51d5f..fda198aa 100644
--- a/bluesky/instrument/iconfig.yml
+++ b/bluesky/instrument/iconfig.yml
@@ -28,6 +28,7 @@ AD_MOUNT_PATH: /tmp
 BLUESKY_MOUNT_PATH: /tmp/docker_ioc/iocad/tmp
 
 # permissions
+ADD_DIAGNOSTIC_MESSAGES: false
 ALLOW_AREA_DETECTOR_WARMUP: true
 ENABLE_AREA_DETECTOR_IMAGE_PLUGIN: true
 ENABLE_CALCS: true
@@ -35,6 +36,7 @@ USE_PROGRESS_BAR: false
 WRITE_NEXUS_DATA_FILES: true
 NEXUS_WARN_MISSING_CONTENT: false
 NEXUS_FILE_EXTENSION: hdf
+VERIFY_FILES_SAVED: False
 WRITE_SPEC_DATA_FILES: true
 
 # ----------------------------------
@@ -52,9 +54,11 @@ WRITE_SPEC_DATA_FILES: true
 LOGGING:
   # MAX_BYTES: 1000000
   NUMBER_OF_PREVIOUS_BACKUPS: 9
-  # LOG_PATH: /tmp
   # If LOG_PATH undefined, this session will log into PWD/logs/
-  # where PWD is present working directory when session is started
+  # where PWD is present working directory when session is started.
+  # LOG_PATH: /tmp
+  # Use "DEBUG" to turn on verbose messages for debugging.
+  OPHYD_LOGGER_LEVEL: WARNING
 
 # default timeouts (seconds)
 PV_READ_TIMEOUT: &TIMEOUT 15

From 78b67382934660d59bdbe678b0430cf661bf388d Mon Sep 17 00:00:00 2001
From: Pete R Jemian <prjemian@users.noreply.github.com>
Date: Mon, 26 Feb 2024 13:14:58 -0600
Subject: [PATCH 11/11] Switch CI to use 'ruff' package for linting (#273)

* DOC #258

* CI #258

* STY #258 changes to comply with 'ruff check'

* CFG #258 ruff configuration

* MNT #258 restore these two imports, they start the instrument

* MNT #258 per 'ruff check'
---
 .github/workflows/code.yml                 | 16 +---
 .ruff.toml                                 | 86 ++++++++++++++++++++++
 .wip/pack_unpack/export_db.py              | 13 ++--
 CHANGES.rst                                |  2 +-
 bluesky/instrument/__init__.py             |  2 +-
 bluesky/instrument/collection.py           |  2 +-
 bluesky/instrument/framework/initialize.py | 14 ++--
 bluesky/instrument/framework/metadata.py   |  1 -
 bluesky/instrument/utils/image_analysis.py |  1 -
 bluesky/qstarter.py                        |  2 +-
 bluesky/tests/test_ipython_startup.py      |  3 +-
 bluesky/tests/test_queueserver_startup.py  |  3 +-
 bluesky/user/quick_hello.py                |  9 ++-
 13 files changed, 118 insertions(+), 36 deletions(-)
 create mode 100644 .ruff.toml

diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml
index 06bf7d0d..4da5017b 100644
--- a/.github/workflows/code.yml
+++ b/.github/workflows/code.yml
@@ -31,19 +31,11 @@ jobs:
         run: |
           set -vxeuo pipefail
           python -m pip install --upgrade pip
-          pip install ruff flake8
-
-      - name: Run flake8
-        run: flake8
   
-      # # TODO: will replace flake8
-      # - name: Run ruff
-      #   uses: davidslusser/actions_python_ruff@v1.0.0
-      #   with:
-      #     # src: "."
-      #     # options: "--cov=src"
-      #     pip_install_command: "pip install -e .[dev]"
-      #     python_version: "3.11"
+      - name: Run ruff
+        uses: davidslusser/actions_python_ruff@v1.0.0
+        with:
+          python_version: "3.11"
 
   tests:
     name: CI py${{ matrix.python-version }}
diff --git a/.ruff.toml b/.ruff.toml
new file mode 100644
index 00000000..f03f66b3
--- /dev/null
+++ b/.ruff.toml
@@ -0,0 +1,86 @@
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+
+# Same as Black.
+line-length = 115
+indent-width = 4
+
+# Assume Python 3.8
+target-version = "py38"
+
+[lint]
+# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
+# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
+# McCabe complexity (`C901`) by default.
+select = ["E4", "E7", "E9", "F"]
+ignore = ["E402", "F405"]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[lint.per-file-ignores]
+"__init__.py" = ["F403"]
+"bluesky/console/__start_bluesky_instrument__.py" = ["F403"]
+"bluesky/instrument/collection.py" = ["F403"]
+"bluesky/instrument/qstarter.py" = ["F401", "F403"]
+"bluesky/instrument/queueserver.py" = ["F401", "F403"]
+"bluesky/qstarter.py" = ["F401"]
+"**/{tests,docs,tools}/*" = ["E402"]
+
+[format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = false
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+docstring-code-line-length = "dynamic"
diff --git a/.wip/pack_unpack/export_db.py b/.wip/pack_unpack/export_db.py
index b5426eb8..b744c1df 100644
--- a/.wip/pack_unpack/export_db.py
+++ b/.wip/pack_unpack/export_db.py
@@ -6,10 +6,12 @@
 see: https://github.com/APS-3ID-IXN/ipython-s3blue/issues/2
 """
 
-from databroker import Broker
-import datetime, os, shutil, time
+import datetime
+import os
+import shutil
+
 import pyRestTable
-from dask.bag import text
+from databroker import Broker
 
 
 def main():
@@ -101,6 +103,7 @@ def main():
 
 
 import re
+
 ACCEPTABLE_PATTERN = r"[A-Za-z_][\w_]*"
 
 
@@ -127,9 +130,7 @@ def tester():
     'mca_elapsed_real_time', 'mca_preset_real_time', 'mca_spectrum',
     'neat_stage_x', 'neat_stage_x_user_setpoint', 'neat_stage_y',
     'neat_stage_y_user_setpoint', 'scaler_time']
-    safe_keys = make_safe(keys)
-    keymap = {k:v for k, v in zip(keys, safe_keys)}
-    for old_key, new_key in zip(keys, safe_keys):
+    for old_key, new_key in zip(keys, make_safe(keys)):
         tbl.addRow((old_key, new_key))
     print(tbl)
 
diff --git a/CHANGES.rst b/CHANGES.rst
index fde197bc..5d4984b1 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -51,10 +51,10 @@ Maintenance
 * Add 'Hello, World!' test to installation checklist.
 * Drop the (unused now) *stdlogpj* package for configuring Python's *logging*.
 * Environment for bluesky_2024_1.
+* Lint the code (for style and syntax errors) using the 'ruff' package.
 * Updates (learned from 2-ID) for new installations.
 * Various documentation updates.
 
-
 v1.0.1
 ******
 
diff --git a/bluesky/instrument/__init__.py b/bluesky/instrument/__init__.py
index 53058682..d9143b9c 100644
--- a/bluesky/instrument/__init__.py
+++ b/bluesky/instrument/__init__.py
@@ -1,2 +1,2 @@
 # instrument configuration
-from ._iconfig import iconfig
+from ._iconfig import iconfig  # noqa
diff --git a/bluesky/instrument/collection.py b/bluesky/instrument/collection.py
index 8e108d54..f6144cfd 100644
--- a/bluesky/instrument/collection.py
+++ b/bluesky/instrument/collection.py
@@ -24,7 +24,7 @@
     logger.info("xmode exception level: '%s'", _xmode_level)
     del _ip
 
-from . import mpl
+from . import mpl  # noqa
 
 logger.info("#### Bluesky Framework ####")
 from .framework import *
diff --git a/bluesky/instrument/framework/initialize.py b/bluesky/instrument/framework/initialize.py
index caff6a4b..b44676da 100644
--- a/bluesky/instrument/framework/initialize.py
+++ b/bluesky/instrument/framework/initialize.py
@@ -26,21 +26,21 @@
 from bluesky import SupplementalData
 from bluesky.callbacks.best_effort import BestEffortCallback
 from bluesky.magics import BlueskyMagics
-from bluesky.simulators import summarize_plan
+from bluesky.simulators import summarize_plan  # noqa
 from bluesky.utils import PersistentDict
 from bluesky.utils import ProgressBarManager
-from bluesky.utils import ts_msg_hook
+from bluesky.utils import ts_msg_hook  # noqa
 from IPython import get_ipython
 from ophydregistry import Registry
 import databroker
 import ophyd
-import warnings
+import warnings  # noqa
 
 # convenience imports
-import bluesky.plans as bp
-import bluesky.plan_stubs as bps
-import bluesky.preprocessors as bpp
-import numpy as np
+import bluesky.plans as bp  # noqa
+import bluesky.plan_stubs as bps  # noqa
+import bluesky.preprocessors as bpp  # noqa
+import numpy as np  # noqa
 
 
 def get_md_path():
diff --git a/bluesky/instrument/framework/metadata.py b/bluesky/instrument/framework/metadata.py
index 551c827e..d4fb9f3f 100644
--- a/bluesky/instrument/framework/metadata.py
+++ b/bluesky/instrument/framework/metadata.py
@@ -15,7 +15,6 @@
 import getpass
 import os
 import socket
-from datetime import datetime
 
 import apstools
 import databroker
diff --git a/bluesky/instrument/utils/image_analysis.py b/bluesky/instrument/utils/image_analysis.py
index 28702e4a..e9118a1b 100644
--- a/bluesky/instrument/utils/image_analysis.py
+++ b/bluesky/instrument/utils/image_analysis.py
@@ -17,7 +17,6 @@
 import numpy as np
 import pyRestTable
 from scipy.ndimage import center_of_mass
-from scipy.integrate import trapz
 
 
 def analyze_peak(y_arr, x_arr=None):
diff --git a/bluesky/qstarter.py b/bluesky/qstarter.py
index e250982b..6acaa215 100644
--- a/bluesky/qstarter.py
+++ b/bluesky/qstarter.py
@@ -22,7 +22,7 @@
 )
 
 from instrument import iconfig
-from instrument.queueserver import *
+from instrument.queueserver import *  # noqa
 
 
 print_instrument_configuration()
diff --git a/bluesky/tests/test_ipython_startup.py b/bluesky/tests/test_ipython_startup.py
index 08a039b3..2cf712ba 100644
--- a/bluesky/tests/test_ipython_startup.py
+++ b/bluesky/tests/test_ipython_startup.py
@@ -6,7 +6,8 @@
 
 
 def test_startup(capsys):
-    from instrument.collection import iconfig
+    # start the instrument package for IPython console session
+    from instrument.collection import iconfig  # noqa
 
     out, err = capsys.readouterr()
 
diff --git a/bluesky/tests/test_queueserver_startup.py b/bluesky/tests/test_queueserver_startup.py
index 0da82e9f..0fb5052a 100644
--- a/bluesky/tests/test_queueserver_startup.py
+++ b/bluesky/tests/test_queueserver_startup.py
@@ -6,7 +6,8 @@
 
 
 def test_startup(capsys):
-    from qstarter import iconfig
+    # start the instrument package for queueserver session
+    from qstarter import iconfig  # noqa
 
     out, err = capsys.readouterr()
 
diff --git a/bluesky/user/quick_hello.py b/bluesky/user/quick_hello.py
index e0cc873f..28a578c0 100644
--- a/bluesky/user/quick_hello.py
+++ b/bluesky/user/quick_hello.py
@@ -16,12 +16,15 @@
 
 import logging
 
+from ophyd import Component
+from ophyd import Device
+from ophyd import Signal
+
+from bluesky import plans as bp
+
 logger = logging.getLogger(__name__)
 logger.info(__file__)
 
-from ophyd import Component, Device, Signal
-
-from bluesky import plans as bp
 
 print("Loading 'Hello, World!' example.")