Merge f787bd3 into 047daf4

BCDA-APS · Apr 5, 2024 · 302301f · 302301f
2 parents 047daf4 + f787bd3
commit 302301f
Show file tree

Hide file tree

Showing 20 changed files with 246 additions and 142 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -50,7 +50,7 @@ jobs:
 
       - name: Install Sphinx build requirements
         run: |
-          pip install -r requirements-sphinx.txt setuptools-scm
+          pip install -r docs/requirements.txt
 
       - name: Install our package
         run: |

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -42,6 +42,7 @@ Maintenance
 
 * Code format conforms to 'ruff'.
 * Add additional support for APS Data Management API.
+* Make the home page more concise.
 * Refactor packaging from setup.py to pyproject.toml.
 
 1.6.18

diff --git a/requirements-sphinx.txt → docs/requirements.txt b/requirements-sphinx.txt → docs/requirements.txt
@@ -8,3 +8,4 @@ pygments >=2.12
 pygments-ipython-console
 setuptools-scm
 sphinx <6
+sphinx-design
diff --git a/docs/source/api/_callbacks.rst b/docs/source/api/_callbacks.rst
@@ -1,9 +1,8 @@
-====================================
-Callbacks (includes File Writers)
-====================================
+.. _callbacks:
 
+=========
 Callbacks
-------------
+=========
 
 .. automodule:: apstools.callbacks.doc_collector
     :members:
@@ -16,4 +15,4 @@ Callbacks
 File Writers
 ------------
 
-See the :ref:`filewriters` section.
+:ref:`filewriters` are a specialized type of callback.
diff --git a/docs/source/api/_filewriters.rst b/docs/source/api/_filewriters.rst
@@ -1,7 +1,8 @@
 .. _filewriters:
 
+============
 File Writers
-------------
+============
 
 The file writer callbacks are:
 

diff --git a/docs/source/api/_plans.rst b/docs/source/api/_plans.rst
@@ -1,3 +1,5 @@
+.. _plans:
+
 ===========
 Plans
 ===========

diff --git a/docs/source/api/_utils.rst b/docs/source/api/_utils.rst
@@ -1,3 +1,5 @@
+.. _utilities:
+
 ==========
 Utilities
 ==========

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -6,6 +6,34 @@ API Documentation
 .. toctree::
    :maxdepth: 2
    :glob:
+   :hidden:
 
    _*
    synApps/index
+
+.. icons: https://fonts.google.com/icons
+.. grid:: 2
+
+    .. grid-item-card:: :ref:`callbacks`
+
+      Receive *documents* from the bluesky RunEngine.
+
+    .. grid-item-card:: :ref:`devices`
+
+      Ophyd-style Devices for the APS.
+
+    .. grid-item-card:: :ref:`filewriters`
+
+      Specialized callbacks to write data in custom formats.
+
+    .. grid-item-card:: :ref:`plans`
+
+      Customize your measurement procedures.
+
+    .. grid-item-card:: :ref:`utilities`
+
+      Python code to assist measurement, data exploration, and the user experience.
+
+    .. grid-item-card:: :ref:`synApps`
+
+      Ophyd-style support for common EPICS structures, including *synApps*.
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -1,3 +1,5 @@
+.. _changes:
+
 ..
 	CHANGES
 	=======

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -68,7 +68,9 @@
     sphinx.ext.viewcode
     nbsphinx
     myst_parser
+    sphinx_design
 """.split()
+myst_enable_extensions = ["colon_fence"]
 
 templates_path = ["_templates"]
 source_suffix = [".rst", ".md"]
@@ -81,6 +83,7 @@
 ]
 html_static_path = ["_static"]
 html_theme = "pydata_sphinx_theme"
+html_title = f"{project} {version}"
 # fmt: off
 html_theme_options = {
     "navbar_start": ["navbar-logo", "version-switcher"],

diff --git a/docs/source/examples/device_examples.rst b/docs/source/examples/device_examples.rst
@@ -0,0 +1,11 @@
+.. _examples.devices:
+
+===============
+Device Examples
+===============
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    de_*
diff --git a/docs/source/examples/download_examples.rst b/docs/source/examples/download_examples.rst
@@ -0,0 +1,25 @@
+.. _examples.downloads:
+
+===============================
+File Downloads for the Examples
+===============================
+
+Jupyter notebooks and files for the :ref:`examples` are available for download:
+
+* jupyter notebook: :download:`de_0_adsim_hdf5_basic <de_0_adsim_hdf5_basic.ipynb>`
+* jupyter notebook: :download:`de_1_adsim_hdf5_custom_names <de_1_adsim_hdf5_custom_names.ipynb>`
+* jupyter notebook: :download:`de_2_adsim_hdf5_single_mode <de_2_adsim_hdf5_single_mode.ipynb>`
+
+* jupyter notebook: :download:`pl_excel_scan <pl_excel_scan.ipynb>`
+
+  * :download:`sample_example.xlsx <sample_example.xlsx>`
+
+* jupyter notebook: :download:`pl_nscan <pl_nscan.ipynb>`
+* jupyter notebook: :download:`pl_tuneaxis <pl_tuneaxis.ipynb>`
+* jupyter notebook: :download:`fw_specfile_example <fw_specfile_example.ipynb>`
+
+  * :download:`spec1.dat <../resources/spec1.dat>`
+  * :download:`spec2.dat <../resources/spec2.dat>`
+  * :download:`spec3.dat <../resources/spec3.dat>`
+  * :download:`spec_tunes.dat <../resources/spec_tunes.dat>`
+  * :download:`test_specdata.txt <../resources/test_specdata.txt>`
diff --git a/docs/source/examples/filewriter_examples.rst b/docs/source/examples/filewriter_examples.rst
@@ -0,0 +1,11 @@
+.. _examples.filewriters:
+
+====================
+File Writer Examples
+====================
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    fw_*
diff --git a/docs/source/examples/howto_examples.rst b/docs/source/examples/howto_examples.rst
@@ -0,0 +1,11 @@
+.. _examples.howto:
+
+====================
+How-To Examples
+====================
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    ho_*
diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -10,70 +10,67 @@ for the APS.  Further, NSLS-II provides online notebooks which can be
 `executed online <https://try.nsls2.bnl.gov>`__ (in a web browser).
 See the `Bluesky home page <https://blueskyproject.io/>`__ for more details.
 
-.. Consider writing new content in one of these categories:
+.. Consider re-organizing and writing new content in one of these categories:
 
   Tutorials
   How-to guides
   Reference
   Explanation
 
-Devices
-++++++++++++++++++++++++++++++++++++
+.. icons: https://fonts.google.com/icons
+.. grid:: 2
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
+    .. grid-item-card:: :material-regular:`precision_manufacturing;3em` Devices
+      :link: device_examples
+      :link-type: doc
 
-   de_*
+      .. toctree::
+         :maxdepth: 1
+         :glob:
+         :hidden:
 
-File Writers
-++++++++++++++++++++++++++++++++++++
+         device_examples
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
+    .. grid-item-card:: :material-regular:`save;3em` File Writers
+      :link: filewriter_examples
+      :link-type: doc
 
-   fw_*
+      .. toctree::
+         :maxdepth: 1
+         :glob:
+         :hidden:
 
-How-to Guides
-++++++++++++++++++++++++++++++++++++
+         filewriter_examples
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
+    .. grid-item-card:: :material-regular:`how_to_reg;3em` How-To
+      :link: howto_examples
+      :link-type: doc
 
-   ho_*
+      .. toctree::
+         :maxdepth: 1
+         :glob:
+         :hidden:
 
-Plans
-++++++++++++++++++++++++++++++++++++
+         howto_examples
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
+    .. grid-item-card:: :material-regular:`task;3em` Plans
+      :link: plan_examples
+      :link-type: doc
 
-   pl_*
+      .. toctree::
+         :maxdepth: 1
+         :glob:
+         :hidden:
 
-.. _examples_downloads:
+         plan_examples
 
-File Downloads for the Examples
-++++++++++++++++++++++++++++++++++++
+    .. grid-item-card:: :material-regular:`download;3em` Downloads
+      :link: download_examples
+      :link-type: doc
 
-The jupyter notebooks and files related to this section may be downloaded from the following table.
+      .. toctree::
+         :maxdepth: 1
+         :glob:
+         :hidden:
 
-* jupyter notebook: :download:`de_0_adsim_hdf5_basic <de_0_adsim_hdf5_basic.ipynb>`
-* jupyter notebook: :download:`de_1_adsim_hdf5_custom_names <de_1_adsim_hdf5_custom_names.ipynb>`
-* jupyter notebook: :download:`de_2_adsim_hdf5_single_mode <de_2_adsim_hdf5_single_mode.ipynb>`
-
-* jupyter notebook: :download:`pl_excel_scan <pl_excel_scan.ipynb>`
-
-  * :download:`sample_example.xlsx <sample_example.xlsx>`
-
-* jupyter notebook: :download:`pl_nscan <pl_nscan.ipynb>`
-* jupyter notebook: :download:`pl_tuneaxis <pl_tuneaxis.ipynb>`
-* jupyter notebook: :download:`fw_specfile_example <fw_specfile_example.ipynb>`
-
-  * :download:`spec1.dat <../resources/spec1.dat>`
-  * :download:`spec2.dat <../resources/spec2.dat>`
-  * :download:`spec3.dat <../resources/spec3.dat>`
-  * :download:`spec_tunes.dat <../resources/spec_tunes.dat>`
-  * :download:`test_specdata.txt <../resources/test_specdata.txt>`
+         download_examples
diff --git a/docs/source/examples/pl_run_command_list.rst b/docs/source/examples/pl_run_command_list.rst
@@ -68,7 +68,7 @@ See :func:`~apstools.plans.parse_text_command_file()` for more details.
 Spreadsheet Command File
 ------------------------
 
-Follow the example spreadsheet (in the :ref:`examples_downloads` section)
+Follow the example spreadsheet (in the :ref:`examples.downloads` section)
 and accompanying Jupyter notebook [#]_ to write your own ``Excel_plan()``.
 
 .. [#] https://github.com/BCDA-APS/apstools/blob/master/docs/source/resources/excel_scan.ipynb

diff --git a/docs/source/examples/plan_examples.rst b/docs/source/examples/plan_examples.rst
@@ -0,0 +1,11 @@
+.. _examples.plans:
+
+====================
+Plan Examples
+====================
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    pl_*