Update the examples

.flake8

@@ -5,6 +5,6 @@ exclude =
     build,
     dist,
     versioneer.py,
-    doc/source
+    docs/source
 max-line-length = 115
 ignore: W504,W503,E741,E402,E226

.github/workflows/conda_unit_test.yml

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

.github/workflows/publish-docs.yml

@@ -0,0 +1,88 @@
+name: Publish Documentation
+
+# comment for normal
+# (For development use)
+# on: push
+
+# comment here and uncomment above to publish docs for _any_ branch
+# (For production use)
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    env:
+      ENV_NAME: test
+      # will define PACKAGE in steps, obtained from GITHUB_REPOSITORY
+
+    if: github.repository_owner == 'bluesky'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - name: get correct package name from repository
+      shell: bash -l {0}
+      run: |
+        echo "PACKAGE=${GITHUB_REPOSITORY##*/}" >> $GITHUB_ENV
+
+    - name: show that
+      shell: bash -l {0}
+      run: |
+        env | sort | grep hklpy
+
+    - uses: actions/checkout@v2
+
+    - name: set environment name in YAML file
+      shell: bash -l {0}
+      run: |
+        sed -i.bak "s/name: ${PACKAGE}/name: ${ENV_NAME}/g" environment.yml
+        head envir*
+
+    - name: Setup Miniconda ${{ matrix.python-version }}
+      uses: conda-incubator/setup-miniconda@v2
+      with:
+        auto-update-conda: true
+        channel-priority: true
+        channels: nsls2forge,conda-forge,defaults
+        environment-file: environment.yml
+        mamba-version: "*"
+        python-version: ${{ matrix.python-version }}
+        use-only-tar-bz2: true  # required for caching
+
+    - name: Install publishing requirements
+      shell: bash -l {0}
+      run: |
+        conda install jupyter nbconvert sphinx sphinxcontrib-napoleon -c defaults -c conda-forge
+        pip install sphinx-rtd-theme
+
+    - name: Install the package locally
+      shell: bash -l {0}
+      run: |
+        pip install -e .
+
+    - name: Build Docs
+      shell: bash -l {0}
+      run: |
+        # conda info
+        # conda list jupyter
+        # conda list nbconvert
+        env | sort | grep -i CONDA
+        make -C examples/
+        make -C docs/ html
+
+    - name: Deploy documentation to blueskyproject.io.
+      # We pin to the SHA, not the tag, for security reasons.
+      # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+      uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
+      with:
+        deploy_key: ${{ secrets.ACTIONS_DOCUMENTATION_DEPLOY_KEY }}
+        publish_branch: master
+        publish_dir: ./docs/build/html
+        external_repository: bluesky/bluesky.github.io
+        destination_dir: ${PACKAGE}
+        keep_files: true  # Keep old files.
+        force_orphan: false  # Keep git history.

.gitignore

@@ -66,8 +66,11 @@ target/
 .ipynb_checkpoints
 
 # generated docs
-doc/source/generated
+docs/source/generated
 
 # Microsoft VS Code editor
 .vscode/
 .history/
+
+# PyTest cache
+.pytest_cache/

docs/source/examples/index.rst

@@ -0,0 +1,36 @@
+.. _examples:
+
+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
+
+Diffractometer Geometries
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/geo_*
+
+Variations
+----------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/var_*
+
+Tests and Comparisons
+---------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   notebooks/tst_*

docs/source/examples/notebooks/.gitignore

@@ -0,0 +1,8 @@
+# ignore any built content from notebooks
+
+# written by nbconvert from root/examples/*.ipynb
+*.rst
+*_files/
+
+# copied from root/examples/resources/*
+resources/

doc/source/index.rst → docs/source/index.rst

@@ -33,11 +33,13 @@ Contents:
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
    calc
    context
    diffract
    engine
    sample
    util
+   examples/*
 

environment.yml

@@ -14,6 +14,7 @@ dependencies:
   - pip
   - prettytable
   - pyepics
+  - pyRestTable
   - pip:
     - coveralls
     - pytest

examples/Makefile

@@ -0,0 +1,22 @@
+# create reStructured text from jupyter notebooks
+#
+# Create the rst files and related resources
+# in the documentation directory.
+
+TARGET_DIR = ../docs/source/examples/notebooks
+NOTEBOOKS := $(wildcard *.ipynb)
+RSTS := $(subst .ipynb,.rst, ${NOTEBOOKS})
+RESOURCES := $(wildcard resources/*)
+
+# default rule: just rebuild everything
+# TODO: could be smarter and rebuild conditionally
+all :: ${RSTS} resources
+
+# copy all the local resources cited in the notebooks
+resources :: #./resources/*
+	mkdir -p ${TARGET_DIR}/resources/
+	cp ${RESOURCES} ${TARGET_DIR}/resources/
+
+# rule to build a rst file from a notebook
+%.rst: %.ipynb
+	jupyter nbconvert --output-dir ${TARGET_DIR} --to rst $<

examples/README.md

@@ -0,0 +1,27 @@
+# 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
+``var_`` | variation on a geometry
+``tst_`` | tests and comparisons
+
+## 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:
+
+TODO: Change these links to `main` branch after PR #52 is merged.
+
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/geo_e4cv.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/geo_e6c.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/geo_k4cv.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/tst_e4cv_fourc.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/tst_e6c_test_calculations.ipynb
+* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/24-examples/examples/var_e4cv_renamed_axes.ipynb