Merge pull request #327 from bluesky/326-pydata_sphinx_theme

Make the home page easier to navigate

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Set update schedule for GitHub Actions
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"

RELEASE_NOTES.rst

@@ -11,10 +11,20 @@ Release History
     Deprecations
     Contributors
 
-v2.0.0 (expected 2024)
-======================================
+..
+    v2.0.0 (expected 2024)
+    ======================================
+
+    User-requested changes
+
+..
+    v1.1.1 (released -tba-)
+    ======================================
+
+    Maintenance
+    -----------
 
-User-requested changes
+    Reorganized the web site docs to be easier to navigate.
 
 v1.1.0 (released 2024-01-13)
 ======================================

docs/make_geometry_tables.py

@@ -18,10 +18,12 @@
 PAGE_HEAD = f"""
 .. this page created by {sys.argv[0]}
 
+.. include:: /substitutions.txt
+
 .. _geometry_tables:
 
 =================================
-Tables of Diffractometer Geometry
+Diffractometer Geometries
 =================================
 
 Tables are provided for the different geometries and then, for each
@@ -34,7 +36,7 @@
 The different diffractometer geometries are distinguished, primarily, by
 the number of axes (circles) and the names of each.  This table is
 sorted first by the number of circles, and then the geometry name (as
-used here in *hklpy*).
+used here in |hklpy|).
 
 """
 

docs/source/api.rst

@@ -1,3 +1,5 @@
+.. _api_documentation:
+
 API Reference
 =============
 
@@ -14,3 +16,9 @@ API Reference
    sample
    user
    util
+
+.. toctree::
+   :glob:
+   :hidden:
+
+   license

docs/source/conf.py

@@ -24,8 +24,8 @@
 project = "hklpy"
 copyright = "2014-2023, Brookhaven National Laboratory"
 # author = 'Bluesky team'
-version = hkl.__version__
-release = version
+release = hkl.__version__
+version = ".".join(release.split(".")[:2])
 short_version = version
 if "+g" in version and ".d2" in version:
     # Extra date (1.0.5.dev146+gbb34ee0.d20231102) makes the title too long.
@@ -45,8 +45,10 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_design",
     "nbsphinx",
 ]
+extensions.append("sphinx_tabs.tabs")  # this must be last
 
 templates_path = ["_templates"]
 exclude_patterns = ["**.ipynb_checkpoints"]
@@ -55,6 +57,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "pydata_sphinx_theme"
+html_title = f"{project} {version}"
 html_static_path = ["_static"]
 
 

docs/source/examples/diffractometer.rst

@@ -0,0 +1,20 @@
+.. include:: /substitutions.txt
+
+.. _examples.diffractometer:
+
+Diffractometer Examples
+-----------------------
+
+See also the documentation for the :ref:`geometries` module.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/geo_*
+
+.. rubric:: Downloads
+
+Most examples are available as `Jupyter notebooks <https://jupyter.org/>`_ on
+the |hklpy| source code website:
+https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks

docs/source/examples/howto.rst

@@ -0,0 +1,18 @@
+.. include:: /substitutions.txt
+
+.. _examples.howto:
+
+How-to Guides
+-------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/how_*
+
+.. rubric:: Downloads
+
+Most examples are available as `Jupyter notebooks <https://jupyter.org/>`_ on
+the |hklpy| source code website:
+https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks

docs/source/examples/notebooks/how_spec_commands.rst

@@ -1,33 +1,37 @@
+.. include:: /substitutions.txt
+
+.. index:: SPEC; commands, hklpy; commands
+
 .. _spec_commands_map:
 
 ========================
 SPEC commands in Bluesky
 ========================
 
-Make it easier for users (especially SPEC users) to learn and remember
-the new tools in Bluesky's *hklpy* package.
+Make it easier for users (especially |spec| users) to learn and remember
+the tools in Bluesky's |hklpy| package.
 
-In addition to the comparison with SPEC commands, more *hklpy* commands
-are listed in the :ref:`user` section.
+See section :ref:`user` for more |hklpy| commands.
 
 .. index:: !Quick Reference Table
 
-Quick Reference Table
+.. rubric:: Quick Reference Table
 
 ===============  =============================================================  ============
-*SPEC*           *hklpy*                                                        description
+|spec|           |hklpy|                                                        description
 ===============  =============================================================  ============
 --               :func:`~hkl.user.select_diffractometer`                        Select the default diffractometer.
 ``pa``           :func:`~hkl.user.pa`                                           Report (full) diffractometer settings.  (pa: print all)
 ``wh``           :func:`~hkl.user.wh`                                           Report (brief) diffractometer settings. (wh: where)
-``br h k l``     ``d_object.move((h, k, l))``                                   Move diffractometer (named here as ``d_object``) motors to the given :math:`h, k, l`.
+``br h k l``     ``d_object.move((h, k, l))``                                   (command line) Move motors of diffractometer ``d_object`` to the given :math:`h, k, l`.  Note the extra parenthesis.
+``br h k l``     ``yield from bps.mv(d_object, (h, k, l))``                     (bluesky plan) Move motors of diffractometer ``d_object`` to the given :math:`h, k, l`.  Note the extra parenthesis.
 ``ca h k l``     :func:`~hkl.user.cahkl`                                        Prints calculated motor settings for the given :math:`h, k, l`.
 ``or_swap``      :func:`~hkl.user.or_swap()`                                    Exchange primary & secondary orientation reflections.
 ``or0``          :func:`~hkl.user.setor`                                        Define a crystal reflection and its motor positions.
 ``or1``          :func:`~hkl.user.setor`                                        Define a crystal reflection and its motor positions.
-``reflex_beg``   :class:`~hkl.configuration.DiffractometerConfiguration`        Initializes the reflections file
-``reflex_end``   :class:`~hkl.configuration.DiffractometerConfiguration`        Closes the reflections file
-``reflex``       :class:`~hkl.configuration.DiffractometerConfiguration`        Adds reflections to the reflections file
+``reflex``       :func:`~hkl.sample.HklSample.affine()`                         Refinement of lattice parameters from list of 3 or more reflections
+``reflex_beg``   not necessary                                                  Initializes the reflections file
+``reflex_end``   not necessary                                                  Closes the reflections file
 ``setlat``       :func:`~hkl.user.update_sample()`                              Update current sample lattice.
 ``setmode``      :func:`~hkl.engine.Engine.mode()`                              Set the diffractometer mode for the `forward()` computation.
 --               :func:`~hkl.diffract.Diffractometer.show_constraints()`        Show the current set of constraints (cut points).

docs/source/examples/t_and_c.rst

@@ -0,0 +1,18 @@
+.. include:: /substitutions.txt
+
+.. _examples.tests:
+
+Tests and Comparisons
+---------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/tst_*
+
+.. rubric:: Downloads
+
+Most examples are available as `Jupyter notebooks <https://jupyter.org/>`_ on
+the |hklpy| source code website:
+https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks

docs/source/examples/variations.rst

@@ -0,0 +1,18 @@
+.. include:: /substitutions.txt
+
+.. _examples.variations:
+
+Variations
+----------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/var_*
+
+.. rubric:: Downloads
+
+Most examples are available as `Jupyter notebooks <https://jupyter.org/>`_ on
+the |hklpy| source code website:
+https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks

docs/source/geometry_tables.rst

@@ -1,10 +1,12 @@
 .. this page created by ./docs/make_geometry_tables.py
 
+.. include:: /substitutions.txt
+
 .. _geometry_tables:
 
-=================================
-Tables of Diffractometer Geometry
-=================================
+=========================
+Diffractometer Geometries
+=========================
 
 .. index:: mode
 
@@ -20,7 +22,7 @@ Geometries indexed by number of circles
 The different diffractometer geometries are distinguished, primarily, by
 the number of axes (circles) and the names of each.  This table is
 sorted first by the number of circles, and then the geometry name (as
-used here in *hklpy*).
+used here in |hklpy|).
 
 
 ======== ================================================================ =======================================================================

docs/source/index.rst

@@ -4,51 +4,51 @@
 hklpy
 =====
 
-Controls for using diffractometers within the `Bluesky Framework
-<https://blueskyproject.io>`_.
+.. include:: /substitutions.txt
 
-Based on the *hkl* library (`documentation
-<https://people.debian.org/~picca/hkl/hkl.html>`_, `source
-<https://repo.or.cz/hkl.git>`_).  (Caution: The GitHub source `repository
-<https://github.com/picca/hkl>`_ may not be synchronized with the latest version
-from repo.or.cz.)
+.. index:: !hklpy
 
-.. ,
-   with slightly cleaner abstractions
-   when compared to the auto-generated gobject-introspection classes.
-
-Integrates with `ophyd <https://blueskyproject.io/ophyd>`_ pseudopositioners
-for use with `bluesky <https://blueskyproject.io/bluesky>`_ plans.
+|hklpy| is a Python package for practical use of diffractometers with the
+`Bluesky Framework <https://blueskyproject.io>`_.
 
 .. toctree::
-   :maxdepth: 2
    :glob:
-   :caption: Core Functionality
+   :hidden:
 
-   overview
-   constraints
+   user_guide
    install
+   api
+   release_notes
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
-   :caption: Ready-to-Use Devices
+.. icons: https://fonts.google.com/icons
 
-   ready_to_use
-   examples/*
+.. grid:: 2
 
-.. toctree::
-   :maxdepth: 2
-   :glob:
-   :caption: Developer Notes
+    .. grid-item-card:: :material-outlined:`summarize;3em` :ref:`user_guide`
 
-   api
-   release_notes
+      How to use |hklpy|
+
+    .. grid-item-card:: :material-regular:`install_desktop;3em` :ref:`install`
+
+      How to install |hklpy|
+
+    .. grid-item-card:: :material-regular:`subscriptions;3em` :ref:`api_documentation`
+
+      About the underlying devices and other support.
+
+    .. grid-item-card:: :material-regular:`history;3em` :ref:`release_notes`
+
+      History of changes.
 
-Indices
--------
+.. _about:
 
-* :ref:`General Index <genindex>`
-* :ref:`Index of Modules <modindex>`
+About
+-----
 
-.. note:: *hklpy* documentation built |today| for version |version|.
+:home: https://bluesky.github.io/hklpy
+:source: https://github.com/bluesky/hklpy
+:license: :ref:`license`
+:full version: |release|
+:published: |today|
+:index: :ref:`genindex`
+:module: :ref:`modindex`