Make it easier to find the SPEC command cross-reference table

RELEASE_NOTES.rst

@@ -29,6 +29,7 @@ Fixes
 Maintenance
 -----------
 
+* Move table with SPEC commands cross-reference to a HOWTO document.
 * ``util.list_orientation_runs()`` added progress bar.
 * Support Py3.8, 3.9, 3.10, & 3.11
 * Support libhkl v5.0.0.3001 (& v5.0.0.3357 when ready)

docs/source/conf.py

@@ -297,7 +297,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/3/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 inheritance_graph_attrs = dict(rankdir="LR")
 inheritance_node_attrs = dict(fontsize=24)
 autosummary_generate = True

docs/source/examples/notebooks/how_spec_commands.rst

@@ -0,0 +1,47 @@
+.. _spec_commands_map:
+
+========================
+SPEC commands in Bluesky
+========================
+
+Make it easier for users (especially SPEC users) to learn and remember
+the new tools in Bluesky's *hklpy* package.
+
+In addition to the comparison with SPEC commands, more *hklpy* commands
+are listed in the :ref:`user` section.
+
+.. index:: !Quick Reference Table
+
+Quick Reference Table
+
+==============  ==================================  ============
+*SPEC*          *hklpy*                             description
+==============  ==================================  ============
+--              :func:`~calc_UB`                    Compute the UB matrix with two reflections.
+--              :func:`~change_sample`              Pick a known sample to be the current selection.
+--              :func:`~list_samples`               List all defined crystal samples.
+--              :func:`~new_sample`                 Define a new crystal sample.
+--              :func:`~select_diffractometer`      Select the default diffractometer.
+``br h k l``    `DIFFRACTOMETER.move(h, k, l)`      move the diffractometer motors to the given :math:`h, k, l`.
+``ca h k l``    `cahkl(h, k, l)`                    Prints calculated motor settings for the given :math:`h, k, l`.
+``cuts``        TODO: constraints
+``cz``          TODO:
+``freeze``      TODO: constraints
+``g_sect``      TODO: constraints
+``mz``          TODO:
+``or_swap``     `or_swap()`                         Exchange primary & secondary orientation reflections.
+``or0``         :func:`~setor`                      Define a crystal reflection and its motor positions.
+``or1``         :func:`~setor`                      Define a crystal reflection and its motor positions.
+``pa``          :func:`~pa`                         Report all diffractometer settings.
+``pl``          TODO:
+``reflex_beg``  TODO:
+``reflex_end``  TODO:
+``reflex``      TODO:
+``setaz``       TODO:
+``setlat``      :func:`~update_sample(...)`         Update current sample lattice.
+``setmode``     TODO: modes
+``setsector``   TODO:
+``sz``          TODO:
+``unfreeze``    TODO: constraints
+``wh``          :func:`~wh`                         Report (brief) where is the diffractometer.
+==============  ==================================  ============

docs/source/user.rst

@@ -6,39 +6,8 @@ user
 Make it easier for users (especially SPEC users) to learn and remember
 the new tools in Bluesky's *hklpy* package.
 
-.. index:: !Quick Reference Table
-
-Quick Reference Table
-
-==============  =======================================
-*SPEC*          *hklpy*
-==============  =======================================
---              :func:`~calc_UB`
---              :func:`~new_sample`
---              :func:`~select_diffractometer`
-``br``          TODO:
-``cal``         :func:`cahkl`
-``cuts``        TODO: constraints
-``cz``          TODO:
-``freeze``      TODO: constraints
-``g_sect``      TODO: constraints
-``mz``          TODO:
-``or_swap``     TODO:
-``or0``         :func:`~setor`
-``or1``         :func:`~setor`
-``pa``          :func:`~pa`
-``pl``          TODO:
-``reflex_beg``  TODO:
-``reflex_end``  TODO:
-``reflex``      TODO:
-``setaz``       TODO:
-``setlat``      :func:`~update_sample`
-``setmode``     TODO: modes
-``setsector``   TODO:
-``sz``          TODO:
-``unfreeze``    TODO: constraints
-``wh``          :func:`~wh`
-==============  =======================================
+See :ref:`spec_commands_map` for a table of SPEC commands and their counterparts
+in *hklpy*.
 
 .. automodule:: hkl.user
     :members:

hkl/user.py

@@ -1,8 +1,8 @@
 """
-Provide a simplified UI for hklpy diffractometer users.
+Provide a simplified interface for hklpy diffractometer users.
 
 The user must define a diffractometer instance, then
-register that instance here calling `select_diffractometer(instance)`.
+register that instance here calling ``select_diffractometer(instance)``.
 
 FUNCTIONS