Merge 137fa02 into 047daf4

BCDA-APS · Apr 5, 2024 · 35c7a00 · 35c7a00
2 parents 047daf4 + 137fa02
commit 35c7a00
Show file tree

Hide file tree

Showing 12 changed files with 80 additions and 48 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,6 +1,8 @@
-====================================
-Callbacks (includes File Writers)
-====================================
+.. _callbacks:
+
+=========
+Callbacks
+=========
 
 Callbacks
 ------------

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/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/index.rst b/docs/source/examples/index.rst
@@ -17,6 +17,8 @@ See the `Bluesky home page <https://blueskyproject.io/>`__ for more details.
   Reference
   Explanation
 
+.. _examples.devices:
+
 Devices
 ++++++++++++++++++++++++++++++++++++
 
@@ -26,6 +28,8 @@ Devices
 
    de_*
 
+.. _examples.filewriters:
+
 File Writers
 ++++++++++++++++++++++++++++++++++++
 
@@ -35,6 +39,8 @@ File Writers
 
    fw_*
 
+.. _examples.howto:
+
 How-to Guides
 ++++++++++++++++++++++++++++++++++++
 
@@ -44,6 +50,8 @@ How-to Guides
 
    ho_*
 
+.. _examples.plans:
+
 Plans
 ++++++++++++++++++++++++++++++++++++
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,43 +2,69 @@
 apstools
 ========
 
-Library of Python tools for use with Bluesky at the APS
+Library of Python tools for use with Bluesky at the APS.
 
-.. toctree::
-   :maxdepth: 1
-   :glob:
-   :caption: Core Functionality
+.. icons: https://fonts.google.com/icons
+.. grid:: 2
 
-   overview
-   applications/index
+    .. grid-item-card:: :material-regular:`home;3em` Introduction
 
-.. toctree::
-   :maxdepth: 3
-   :glob:
-   :caption: Examples & Guides
+      Get acquainted with *apstools*.
 
-   examples/index
+      * :ref:`overview`
+      * :ref:`install`
 
-.. toctree::
-   :maxdepth: 3
-   :glob:
-   :caption: Developer Notes
+    .. grid-item-card:: :material-regular:`apps;3em` :ref:`applications`
+      :link: applications/index
+      :link-type: doc
 
-   api/index
+      Applications provided by *apstools*.
+
+    .. grid-item-card:: :material-regular:`api;3em` :ref:`api_documentation`
+
+      Libraries in the *apstools* package.
+
+      * :ref:`callbacks`
+      * :ref:`devices`
+      * :ref:`filewriters`
+      * :ref:`plans`
+      * :ref:`utilities`
+      * :ref:`synApps <synApps>`
+
+    .. grid-item-card:: :material-regular:`alt_route;3em` :ref:`examples`
+
+      Examples using the *apstools* package, many with Jupyter notebooks.
+
+
+      * :ref:`examples.devices`
+      * :ref:`examples.filewriters`
+      * :ref:`examples.howto`
+      * :ref:`examples.plans`
+
+------------
 
 .. toctree::
    :maxdepth: 1
-   :glob:
-   :caption: Package Details
+   :hidden:
 
+   overview
    install
+   applications/index
+   api/index
+   examples/index
    changes
    license
 
 
-Indices and tables
-==================
+About
+-----
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+:home: https://bcda-aps.github.io/apstools
+:source: https://github.com/bcda-aps/apstools
+:license: :ref:`license`
+:full version: |release|
+:published: |today|
+:revisions: :ref:`History of code changes <changes>`
+:index: :ref:`genindex`
+:module: :ref:`modindex`
+:search: :ref:`search`
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -3,9 +3,6 @@
 Installation
 ============
 
-Installation
-############
-
 The ``apstools`` package is available for installation
 by ``conda``, ``pip``, or from source.
 
@@ -15,9 +12,7 @@ conda
 If you are using Anaconda Python and have ``conda`` installed, install the most
 recent version with this command::
 
-    $ conda install -c conda-forge apstools
-
-..    $ conda install -c aps-anl-tag apstools
+    $ conda install conda-forge::apstools
 
 pip
 ---
@@ -43,21 +38,9 @@ To install from the source directory using ``pip`` in editable mode::
     $ python -m pip install -e .
 
 Required Libraries
-##################
+------------------
 
 The repository's ``environment.yml`` file lists the additional packages
 required by ``apstools``.  Most packages are available as conda packages
 from https://anaconda.org.  The others are available on
-https://PyPI.python.org.  Among the required packages:
-
-  - python>=3.7
-  - bluesky, databroker, ophyd
-  - h5py
-  - pandas
-  - pyEpics
-  - pyqt=5
-  - pyRestTable
-  - qt=5
-  - spec2nexus
-  - xlrd
-
+https://PyPI.python.org.
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -1,3 +1,5 @@
+.. _overview:
+
 ========
 Overview
 ========