Merge b4f2913 into d2b5f4c

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/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,31 +9,52 @@ 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.  Documentation is categorized in major sections.
+
+.. icons: https://fonts.google.com/icons
+
+.. grid:: 2
+
+    .. grid-item-card:: :material-regular:`alt_route;3em`
+      :link: howto/index
+      :link-type: doc
+
+      :ref:`howto`
+
+      Practical guides for accomplishing specific tasks.
+
+      .. rubric:: :ref:`examples`
+
+      Demonstrations of specific tasks.
+
+    .. grid-item-card::  :material-regular:`precision_manufacturing;3em`
+
+      :ref:`instrument`
+
+      Details to configure and develop your *instrument* package.
+
+      .. rubric:: `Template <https://github.com/BCDA-APS/bluesky_training/tree/main/bluesky>`_
+
+      The ``bluesky/`` `directory
+      <https://github.com/BCDA-APS/bluesky_training/tree/main/bluesky>`_ is the
+      template for new beamline :ref:`installations <checklist>`.
+
+    .. grid-item-card:: :material-regular:`school;3em`
+      :link: tutor/index
+      :link-type: doc
+
+      :ref:`tutorials`
+
+      Step-by-step guides to help you get started and learn through doing.
+
+    .. grid-item-card:: :material-regular:`collections_bookmark;3em`
+      :link: reference/index
+      :link-type: doc
+
+      :ref:`reference`
+
+      More ways to learn more about Bluesky.
 
 .. toctree::
    :maxdepth: 1
@@ -54,42 +67,14 @@ of the documentation.
    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`