Merge pull request #956 from BCDA-APS/955-safer-home

Make the home page friendlier
BCDA-APS · Apr 10, 2024 · 14060fd · 14060fd
2 parents 0769f87 + 9e802ec
commit 14060fd
Show file tree

Hide file tree

Showing 22 changed files with 223 additions and 175 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: |
@@ -78,6 +78,15 @@ jobs:
         run: |
           TZ=UTC sphinx-build -M html ./docs/source "${TMP_DIR}/build"
 
+      - name: Build Info
+        run: ls -lAFghR "${TMP_DIR}/build/html"
+
+      - name: Upload Docs ZIP file as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: apstools-docs
+          path: ${{ env.TMP_DIR }}/build/html
+
       - name: Re-build the master directory (contains all documentation versions)
         run: |
           set -vxeuo pipefail

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -28,7 +28,7 @@ describe future plans.
 1.6.19
 ******
 
-release expected by 2024-04-02
+release expected by 2024-04-12
 
 Fixes
 -----
@@ -43,6 +43,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,10 @@
-====================================
-Callbacks (includes File Writers)
-====================================
+.. _callbacks:
 
+=========
 Callbacks
-------------
+=========
+
+Receive *documents* from the bluesky RunEngine.
 
 .. automodule:: apstools.callbacks.doc_collector
     :members:
@@ -16,4 +17,4 @@ Callbacks
 File Writers
 ------------
 
-See the :ref:`filewriters` section.
+:ref:`filewriters` are a specialized type of callback.
diff --git a/docs/source/api/_devices.rst b/docs/source/api/_devices.rst
@@ -4,8 +4,7 @@
 Devices
 =======
 
-Devices (subclasses of ophyd's `Device`) that might be useful at the APS using
-Bluesky.
+Ophyd-style Devices for the APS.
 
 Also consult the :ref:`Index <genindex>` under the *Ophyd* heading for
 links to the Devices, Exceptions, Mixins, Signals, and other support

diff --git a/docs/source/api/_filewriters.rst b/docs/source/api/_filewriters.rst
@@ -1,9 +1,10 @@
 .. _filewriters:
 
+============
 File Writers
-------------
+============
 
-The file writer callbacks are:
+Write data files during data acquisition.  The file writer callbacks are:
 
 .. autosummary::
 
@@ -124,6 +125,8 @@ versions    instrument    documents the software versions used to collect data
 For more information about Bluesky *events* and document types, see
 https://blueskyproject.io/event-model/data-model.html.
 
+.. _filewriters.NXWriter:
+
 NXWriter
 ^^^^^^^^
 
@@ -369,6 +372,7 @@ Examples of additional structure in NeXus file added by
     :linenos:
     :language: text
 
+.. _filewriters.SpecWriterCallback:
 
 SPEC File Structure
 +++++++++++++++++++

diff --git a/docs/source/api/_plans.rst b/docs/source/api/_plans.rst
@@ -1,8 +1,10 @@
+.. _plans:
+
 ===========
 Plans
 ===========
 
-Plans that might be useful at the APS when using Bluesky.
+Customize your measurement procedures.
 
 Plans and Support by Activity
 ------------------------------

diff --git a/docs/source/api/_utils.rst b/docs/source/api/_utils.rst
@@ -1,8 +1,10 @@
+.. _utilities:
+
 ==========
 Utilities
 ==========
 
-Various utilities to help APS use the Bluesky framework.
+Assists measurement, data exploration, and the user experience.
 
 Also consult the :ref:`Index <genindex>` under the *apstools* heading
 for links to the Exceptions, and Utilities described

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -3,9 +3,39 @@
 API Documentation
 =================
 
+Ophyd-style support for EPICS & synApps structures (records and databases).
+
 .. toctree::
    :maxdepth: 2
    :glob:
+   :hidden:
 
    _*
    synApps/index
+
+.. icons: https://fonts.google.com/icons
+.. grid:: 2
+
+    .. grid-item-card:: :material-regular:`subscriptions;3em` :ref:`callbacks`
+
+      Receive *documents* from the bluesky RunEngine.
+
+    .. grid-item-card:: :material-regular:`precision_manufacturing;3em` :ref:`devices`
+
+      Ophyd-style Devices for the APS.
+
+    .. grid-item-card:: :material-regular:`save;3em` :ref:`filewriters`
+
+      Write data files during data acquisition.
+
+    .. grid-item-card:: :material-regular:`task;3em` :ref:`plans`
+
+      Customize your measurement procedures.
+
+    .. grid-item-card:: :material-regular:`support;3em` :ref:`synApps`
+
+      Ophyd-style support for common EPICS structures, including *synApps*.
+
+    .. grid-item-card:: :material-regular:`plumbing;3em` :ref:`utilities`
+
+      Assists measurement, data exploration, and the user experience.
diff --git a/docs/source/api/synApps/index.rst b/docs/source/api/synApps/index.rst
@@ -1,8 +1,8 @@
 .. _synApps:
 
-=============================================
-synApps Support: Records, Databases, ...
-=============================================
+=======
+synApps
+=======
 
 Ophyd-style support for EPICS synApps structures (records and databases).
 

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