Merge 184cb12 into d2b5f4c

bluesky/instrument/framework/initialize.py

@@ -56,6 +56,7 @@ def get_md_path():
     logger.info("RunEngine metadata saved in directory: %s", str(path))
     return str(path)
 
+
 # Set up a RunEngine and use metadata backed PersistentDict
 RE = RunEngine({})
 RE.md = PersistentDict(get_md_path())

docs/requirements.txt

@@ -9,4 +9,5 @@ pydata-sphinx-theme
 pygments >=2.12
 pygments-ipython-console
 sphinx <6
+sphinx-design
 sphinx-tabs

docs/source/conf.py

@@ -26,8 +26,10 @@
     sphinx.ext.viewcode
     nbsphinx
     myst_parser
+    sphinx_design
 """.split()
 extensions.append("sphinx_tabs.tabs")  # issue #129: this must be last
+myst_enable_extensions = ["colon_fence"]
 
 templates_path = ["_templates"]
 source_suffix = ".rst .md".split()
@@ -43,6 +45,7 @@
 
 html_static_path = ["_static"]
 html_theme = "pydata_sphinx_theme"
+html_title = project
 
 autodoc_mock_imports = """
     bluesky

docs/source/howto/_dynamic_limits_2motor.ipynb

@@ -805,8 +805,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Following this example: https://blueskyproject.io/bluesky/state-machine.html#example-suspend-a-plan-if-the-beam-current-dips-low,\n",
-    "we'll do similar but know that our signal is a boolean, that indicates *no permit* when low.  Suspends interrupt the `RE` as long as the signal is invalid and automatically resume if the signal becomes valid again.  Let's see how this works here."
+    "The Bluesky project shows [how to suspend a plan when the source X-ray intensity drops too low](https://blueskyproject.io/bluesky/main/state-machine.html#example-suspend-a-plan-if-the-beam-current-dips-low).\n",
+    "\n",
+    "Following this example, we'll do similar.  In our case, the signal is a boolean\n",
+    "that indicates *no permit* when low.  The suspender interrupts the `RE` as long\n",
+    "as the signal is invalid and automatically resumes if the signal becomes valid\n",
+    "again.  Let's see how this works here."
    ]
   },
   {

docs/source/howto/index.rst

@@ -15,7 +15,7 @@ How-To Guides
 
 How-to guides are directions that take the reader through the steps required to
 solve a real-world problem. How-to guides are *goal-oriented*.
-Tutorials often involve more depth than HowTo guides.
+(Tutorials often involve more depth than HowTo guides.)
 
 .. toctree::
    :maxdepth: 2

docs/source/index.rst

@@ -1,14 +1,6 @@
 APS Bluesky Training
 ====================
 
-The APS Bluesky Training repository [#]_ demonstrates use of the Bluesky
-framework at a typical APS beamline.  Its ``bluesky/`` directory [#]_ also
-serves as a template for new beamline installations.
-
-.. [#] repository: https://github.com/BCDA-APS/bluesky_training
-.. [#] ``bluesky/`` directory: new beamline
-   `template <https://github.com/BCDA-APS/bluesky_training/tree/main/bluesky>`__
-
 .. for documentation authors:
    Documentation may be created in restructured text (.rst), markdown (.md)
    of Jupyter notebooks (.ipynb).  Add new documents to the appropriate folder
@@ -17,79 +9,64 @@ 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.
-   -  `Plot x, y data from a databroker run <https://bcda-aps.github.io/bluesky_training/howto/_plot_x_y_databroker.html>`_
-   -  `Working with data after the measurement <https://bcda-aps.github.io/bluesky_training/howto/_after_measurement.html>`_
-- :ref:`instrument`
-   -  `Installation Guide <https://bcda-aps.github.io/bluesky_training/instrument/_install_new_instrument.html>`_:
-      Install the components of the Bluesky framework.
-   -  `Template <https://github.com/BCDA-APS/bluesky_training/tree/main/bluesky/instrument>`_
-      for a bluesky ``instrument``
-   -  `Instrument Package Guide <instrument/guide.md>`__:
-      Building the ``instrument`` package.
-   - `About the instrument package <file:///home/prjemian/Documents/projects/BCDA-APS/bluesky_training/docs/build/html/instrument/describe_instrument.html>`_
-- :ref:`examples`
-   - `XAFS scan <https://bcda-aps.github.io/bluesky_training/example/_xafs_scan.html>`_ : Example multi-segment XAFS scan.
-- :ref:`Tutorials and Lessons <tutorials>`
-   - `Hello, World <https://bcda-aps.github.io/bluesky_training/tutor/hello_world.html>`_
-   - `Connect Bluesky with EPICS <https://bcda-aps.github.io/bluesky_training/tutor/connect_epics.html>`_
-- :ref:`reference`
-   -  `bluesky training wiki <https://github.com/BCDA-APS/bluesky_training/wiki>`_:
-      Includes list of APS instruments
-   -  `General Bluesky Documentation (for APS) <https://wiki-ext.aps.anl.gov/blc/index.php?title=Controls_Software_Documentation#Bluesky>`_
+This APS Bluesky Training repository demonstrates use of the Bluesky framework
+at a typical APS beamline.
+
+.. icons: https://fonts.google.com/icons
+
+.. grid:: 2
+
+    .. grid-item-card:: :material-regular:`list_alt;3em` :ref:`instrument.install`
+
+      Install a new ``bluesky`` directory and get started.
+
+    .. grid-item-card:: :material-regular:`precision_manufacturing;3em` :ref:`instrument`
+
+      Customize your control system with Bluesky.
+
+    .. grid-item-card:: :material-regular:`straight;3em` :ref:`examples`
+
+      See real-case scenarios of the Bluesky framework in action.
+
+    .. grid-item-card:: :material-regular:`alt_route;3em` :ref:`howto`
+
+      Step-by-step instructions tailored for you to master specific Bluesky tasks.
+
+    .. grid-item-card:: :material-regular:`school;3em` :ref:`tutorials`
+
+      Step-by-step guides to help you get started and learn through doing.
+
+    .. grid-item-card::  :material-regular:`precision_manufacturing;3em` `Template <https://github.com/BCDA-APS/bluesky_training/tree/main/bluesky>`_
+
+      The pristine model of your ``bluesky`` directory.
+
+    .. grid-item-card:: :material-regular:`question_mark;3em` :ref:`FAQ`
+
+      Some commonly-asked questions concerning Bluesky.
+
+    .. grid-item-card:: :material-regular:`collections_bookmark;3em` :ref:`reference`
+
+      Learn more about Bluesky.
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
-   howto/index
    instrument/index
    example/index
+   howto/index
    tutor/index
    reference/index
    changes
 
-Other resources
-==================
-
-* apstools
-   * home: https://bcda-aps.github.io/apstools/latest/
-   * source: https://github.com/BCDA-APS/apstools
-   * PyPI: https://pypi.org/project/apstools/
-   * conda: https://anaconda.org/conda-forge/apstools
-* Bluesky framework
-   * home: https://blueskyproject.io
-   * source: https://github.com/bluesky
-   * conda: all packages available on conda-forge channel
-* MongoDB
-   * home: https://www.mongodb.com/
-* PyDM
-   * home: https://slaclab.github.io/pydm/
-   * source: https://github.com/slaclab/pydm
-   * PyPI: https://pypi.org/project/pydm/
-   * conda: https://anaconda.org/conda-forge/pydm
-* PyEPICS
-   * home: https://pyepics.github.io/pyepics/
-   * source: https://github.com/pyepics/pyepics
-   * PyPI: https://pypi.org/project/pyepics/
-   * conda: https://anaconda.org/conda-forge/pyepics
-* APS Data Management
-   * home: https://confluence.aps.anl.gov/display/DMGT/
-
-Revision History
-==================
-
-:ref:`History of code changes <changes>`
-
-Index
-==================
-
-* :ref:`genindex`
+About
+-----
+
+:home: https://bcda-aps.github.io/bluesky_training/
+:source: https://github.com/bcda-aps/bluesky_training
+:published: |today|
+:revisions: :ref:`History of code changes <changes>`
+:index: :ref:`genindex`
 
 .. * :ref:`modindex`
 .. * :ref:`search`

docs/source/instrument/_activate_environment.rst

@@ -0,0 +1,46 @@
+.. _instrument.activate_bluesky_conda_environment:
+
+Activate the bluesky conda environment
+--------------------------------------
+
+.. note:: Consider merging with :ref:`reference.create_bluesky_enviroment`
+
+.. TODO: instead of dropdown, make a paragraph that references the extra help page
+   If you need to install a bluesky conda environment, see these instruction...
+   See these instructions (link) if you need to create a bluesky conda environment.
+   MAKE SURE THE TITLE names match.  Use :ref: anchors.
+
+.. raw:: html
+
+   <details>
+   <summary>How to create a conda environment for bluesky?</summary>
+
+   See <a href="https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html">here</a>.
+
+   </details>
+
+To use bluesky, you first need to activate the bluesky conda environment:
+
+.. raw:: html
+
+   <pre>
+   $ <b>conda activate bluesky_2023_3</b>
+   </pre>
+
+The prompt changes to display ``(bluesky_2023_3)`` .
+
+.. raw:: html
+
+   <details>
+   <summary>How to create an alias to activate the bluesky environment?</summary>
+
+   See <a href="https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html#create-an-alias-to-activate-the-bluesky-environment">here</a>.
+   </details>
+
+
+
+This activation will remain in effect for the duration of the session
+(*i.e.* as long as the terminal stays open), unless you activate a
+different environment or deactivate it using the ``conda deactivate``
+command.
+