Publish jupyter notebooks directly from documentation source dir

.github/workflows/conda_unit_test.yml

@@ -64,6 +64,6 @@ jobs:
     - name: Test with coverage and pytest
       shell: bash -l {0}
       run: |
-        coverage run --concurrency=thread --parallel-mode -m pytest -vvv --ignore=examples
+        coverage run --concurrency=thread --parallel-mode -m pytest -vvv
         coverage combine
         coverage report

.github/workflows/publish-docs.yml

@@ -56,7 +56,7 @@ jobs:
     - name: Install publishing requirements
       shell: bash -l {0}
       run: |
-        conda install jupyter nbconvert sphinx sphinxcontrib-napoleon make flake8 black pandoc -c defaults -c conda-forge
+        conda install jupyter nbconvert sphinx nbsphinx sphinxcontrib-napoleon make flake8 black pandoc -c defaults -c conda-forge
         pip install sphinx-rtd-theme
 
     - name: Install the package locally
@@ -71,8 +71,7 @@ jobs:
         # conda list jupyter
         # conda list nbconvert
         env | sort | grep -i CONDA
-        # make -C examples/
-        # make -C docs/ html
+        # make html
         make
 
     - name: Deploy documentation to blueskyproject.io.

MANIFEST.in

@@ -10,7 +10,7 @@ include requirements.txt
 include versioneer.py
 
 recursive-include docs *.rst conf.py Makefile make.bat
-recursive-include examples Makefile README.md *.ipynb resources/*
+recursive-include Makefile README.md *.ipynb resources/*
 
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

Makefile

@@ -2,20 +2,11 @@
 
 # Simplify the pre-commit checks for the code developer.
 
-all :: black flake8 pytest clean_docs examples html
+all :: black flake8 pytest html
 
 black ::
 	black .
 
-clean_docs ::
-	make -C docs clean
-	rm -rf docs/source/examples/notebooks/geo_*
-	rm -rf docs/source/examples/notebooks/tst_*
-	rm -rf docs/source/examples/notebooks/var_*
-
-examples ::
-	make -C examples
-
 flake8 ::
 	flake8
 

docs/source/conf.py

@@ -43,6 +43,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",  # see NOTE below
     "sphinx.ext.viewcode",
+    "nbsphinx",
 ]
 # NOTE: Requires sphinxcontrib-napoleon from conda-forge or PyPI.
 
@@ -83,7 +84,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ["**.ipynb_checkpoints"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = None

docs/source/examples/index.rst

@@ -3,10 +3,9 @@
 Examples
 ========
 
-All examples are available as
-`Jupyter notebooks <https://jupyter.org/>`_
-from the *hklpy* source
-code website: https://github.com/bluesky/hklpy/tree/main/examples
+All 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
 
 .. _examples.diffractometer:
 

docs/source/examples/notebooks/README.md

@@ -0,0 +1,32 @@
+# Examples
+
+## file names
+
+To facilitate automatic sorting in the documentation, a file naming
+convention is set forth for the examples.  The convention is to prefix
+the file names.
+
+prefix   | type of example
+------   | -------
+``geo_`` | diffractometer geometry example
+``how_`` | How-to guide
+``var_`` | variation on a geometry
+``tst_`` | tests or comparison
+
+## notebook views
+
+The examples can be viewed directly as notebooks in most web
+browsers.  If an example fails to load properly, try using this
+convenient web tool to view:
+
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/geo_e4cv.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/geo_e6c.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/geo_k4cv.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/how_additional_parameters.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/how_extra_real_axis.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/tst_e4cv_fourc.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/tst_e6c_test_calculations.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/tst_UB_in_descriptor_document.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/var_e4cv_renamed_axes.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/var_engines.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/docs/source/examples/notebooks/var_nslsii_tardis.ipynb

examples/geo_e4cv.ipynb → docs/source/examples/notebooks/geo_e4cv.ipynb

@@ -20,7 +20,7 @@
     "\n",
     "Note:  This example is available as a\n",
     "[Jupyter notebook](https://jupyter.org/) from the *hklpy* source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples"
+    "code website: https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks"
    ]
   },
   {

examples/geo_e6c.ipynb → docs/source/examples/notebooks/geo_e6c.ipynb

@@ -16,7 +16,7 @@
     "\n",
     "Note:  This example is available as a\n",
     "[Jupyter notebook](https://jupyter.org/) from the *hklpy* source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples"
+    "code website: https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks"
    ]
   },
   {

examples/geo_k4cv.ipynb → docs/source/examples/notebooks/geo_k4cv.ipynb

@@ -13,7 +13,7 @@
     "\n",
     "Note:  This example is available as a\n",
     "[Jupyter notebook](https://jupyter.org/) from the *hklpy* source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples"
+    "code website: https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks"
    ]
   },
   {

examples/how_additional_parameters.ipynb → docs/source/examples/notebooks/how_additional_parameters.ipynb

@@ -52,7 +52,7 @@
     "engine | `hkl`\n",
     "mode | `double_diffraction`\n",
     "\n",
-    "Using the standard `E4CV` geometry with simulated motors, we copy the [E4CV setup for the *LNO_LAO* sample](https://blueskyproject.io/hklpy/examples/notebooks/tst_e4cv_fourc.html#read-the-spec-scan-from-the-data-file).  Using a kwarg, we can automatically compute the UB matrix once we define the second reflection.  (This means we do not have to call `compute_UB()` on a separate line.)"
+    "Using the standard `E4CV` geometry with simulated motors, we copy the [E4CV setup for the *LNO_LAO* sample](https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks/tst_e4cv_fourc.html#read-the-spec-scan-from-the-data-file).  Using a kwarg, we can automatically compute the UB matrix once we define the second reflection.  (This means we do not have to call `compute_UB()` on a separate line.)"
    ]
   },
   {

examples/how_extra_real_axis.ipynb → docs/source/examples/notebooks/how_extra_real_axis.ipynb

@@ -22,7 +22,7 @@
    "source": [
     "## Standard 4-circle\n",
     "\n",
-    "First, we start with the setup of a [4-circle diffractometer](https://blueskyproject.io/hklpy/examples/notebooks/geo_e4cv.html#define-this-diffractometer) (E4CV is the name of the geometry).  The [E4CV geometry](https://blueskyproject.io/hklpy/geometry_tables.html#geometries-indexed-by-number-of-circles) requires these real positioners for the diffractometer circles: `omega`, `chi`, `phi`, and `tth`.  For simulated axes without using EPICS, we use the [ophyd.SoftPositioner](https://blueskyproject.io/ophyd/positioners.html#softpositioner).  We'll use the (default) [hkl calculation engine](https://blueskyproject.io/hklpy/geometry_tables.html#e4cv-table) which requires pseudo-positioners `h`, `k`, and `l`.  These pseudo-positioners are provided by the `hkl.geometries.SimMixin` class."
+    "First, we start with the setup of a [4-circle diffractometer](https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks/geo_e4cv.html#define-this-diffractometer) (E4CV is the name of the geometry).  The [E4CV geometry](https://blueskyproject.io/hklpy/geometry_tables.html#geometries-indexed-by-number-of-circles) requires these real positioners for the diffractometer circles: `omega`, `chi`, `phi`, and `tth`.  For simulated axes without using EPICS, we use the [ophyd.SoftPositioner](https://blueskyproject.io/ophyd/positioners.html#softpositioner).  We'll use the (default) [hkl calculation engine](https://blueskyproject.io/hklpy/geometry_tables.html#e4cv-table) which requires pseudo-positioners `h`, `k`, and `l`.  These pseudo-positioners are provided by the `hkl.geometries.SimMixin` class."
    ]
   },
   {

examples/tst_e4cv_fourc.ipynb → docs/source/examples/notebooks/tst_e4cv_fourc.ipynb

@@ -16,7 +16,7 @@
     "\n",
     "Note:  This example is available as a\n",
     "[Jupyter notebook](https://jupyter.org/) from the **hklpy** source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples"
+    "code website: https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks"
    ]
   },
   {

examples/tst_e6c_test_calculations.ipynb → docs/source/examples/notebooks/tst_e6c_test_calculations.ipynb

@@ -15,9 +15,9 @@
     "\n",
     "----\n",
     "\n",
-    "Note:  This example is available as a\n",
-    "[Jupyter notebook](https://jupyter.org/) from the *hklpy* source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples\n",
+    "Note:  This example is available as a [Jupyter notebook](https://jupyter.org/)\n",
+    "from the *hklpy* source code website:\n",
+    "https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks\n",
     "\n",
     "### Import the Python libraries needed"
    ]
@@ -472,4 +472,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

examples/var_e4cv_renamed_axes.ipynb → docs/source/examples/notebooks/var_e4cv_renamed_axes.ipynb

@@ -38,7 +38,7 @@
     "\n",
     "Note:  This example is available as a\n",
     "[Jupyter notebook](https://jupyter.org/) from the *hklpy* source\n",
-    "code website: https://github.com/bluesky/hklpy/tree/main/examples"
+    "code website: https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks"
    ]
   },
   {

env-dev.yml

@@ -20,6 +20,7 @@ dependencies:
   - hkl
   - ipython
   - jupyter
+  - nbsphinx
   - numpy
   - ophyd
   - packaging