diff --git a/.github/workflows/conda_unit_test.yml b/.github/workflows/conda_unit_test.yml index badc1f40..886ad3cf 100644 --- a/.github/workflows/conda_unit_test.yml +++ b/.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 diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 6318060a..0e39df03 100644 --- a/.github/workflows/publish-docs.yml +++ b/.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. diff --git a/MANIFEST.in b/MANIFEST.in index d5434e43..21901847 100644 --- a/MANIFEST.in +++ b/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] diff --git a/Makefile b/Makefile index f9074737..67d6912c 100644 --- a/Makefile +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 9b77fb68..589d7a73 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 0152e4c8..4cb97bac 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -3,10 +3,9 @@ Examples ======== -All examples are available as -`Jupyter notebooks `_ -from the *hklpy* source -code website: https://github.com/bluesky/hklpy/tree/main/examples +All examples are available as `Jupyter notebooks `_ on +the *hklpy* source code website: +https://github.com/bluesky/hklpy/tree/main/docs/source/examples/notebooks .. _examples.diffractometer: diff --git a/docs/source/examples/notebooks/.gitignore b/docs/source/examples/notebooks/.gitignore deleted file mode 100644 index 524499c6..00000000 --- a/docs/source/examples/notebooks/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# ignore any built content from notebooks - -# written by nbconvert from root/examples/*.ipynb -*.rst -*_files/ - -# copied from root/examples/resources/* -resources/ diff --git a/docs/source/examples/notebooks/README.md b/docs/source/examples/notebooks/README.md new file mode 100644 index 00000000..40e67e2b --- /dev/null +++ b/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 diff --git a/examples/geo_e4cv.ipynb b/docs/source/examples/notebooks/geo_e4cv.ipynb similarity index 99% rename from examples/geo_e4cv.ipynb rename to docs/source/examples/notebooks/geo_e4cv.ipynb index c4fa4039..612ea6a8 100644 --- a/examples/geo_e4cv.ipynb +++ b/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" ] }, { diff --git a/examples/geo_e6c.ipynb b/docs/source/examples/notebooks/geo_e6c.ipynb similarity index 99% rename from examples/geo_e6c.ipynb rename to docs/source/examples/notebooks/geo_e6c.ipynb index 2c14a722..6060e900 100644 --- a/examples/geo_e6c.ipynb +++ b/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" ] }, { diff --git a/examples/geo_k4cv.ipynb b/docs/source/examples/notebooks/geo_k4cv.ipynb similarity index 99% rename from examples/geo_k4cv.ipynb rename to docs/source/examples/notebooks/geo_k4cv.ipynb index 4e9e9a80..daac54f2 100644 --- a/examples/geo_k4cv.ipynb +++ b/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" ] }, { diff --git a/examples/how_additional_parameters.ipynb b/docs/source/examples/notebooks/how_additional_parameters.ipynb similarity index 95% rename from examples/how_additional_parameters.ipynb rename to docs/source/examples/notebooks/how_additional_parameters.ipynb index f4c4391d..9e752e7d 100644 --- a/examples/how_additional_parameters.ipynb +++ b/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.)" ] }, { diff --git a/examples/how_extra_real_axis.ipynb b/docs/source/examples/notebooks/how_extra_real_axis.ipynb similarity index 95% rename from examples/how_extra_real_axis.ipynb rename to docs/source/examples/notebooks/how_extra_real_axis.ipynb index 1c6fe7d9..d4a2860c 100644 --- a/examples/how_extra_real_axis.ipynb +++ b/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." ] }, { diff --git a/docs/source/examples/notebooks/resources/.keep b/docs/source/examples/notebooks/resources/.keep deleted file mode 100644 index e69de29b..00000000 diff --git a/examples/resources/3S+1D.png b/docs/source/examples/notebooks/resources/3S+1D.png similarity index 100% rename from examples/resources/3S+1D.png rename to docs/source/examples/notebooks/resources/3S+1D.png diff --git a/examples/resources/4S+2D-labeled.png b/docs/source/examples/notebooks/resources/4S+2D-labeled.png similarity index 100% rename from examples/resources/4S+2D-labeled.png rename to docs/source/examples/notebooks/resources/4S+2D-labeled.png diff --git a/examples/resources/4S+2D-photo.jpg b/docs/source/examples/notebooks/resources/4S+2D-photo.jpg similarity index 100% rename from examples/resources/4S+2D-photo.jpg rename to docs/source/examples/notebooks/resources/4S+2D-photo.jpg diff --git a/examples/resources/4S+2D.png b/docs/source/examples/notebooks/resources/4S+2D.png similarity index 100% rename from examples/resources/4S+2D.png rename to docs/source/examples/notebooks/resources/4S+2D.png diff --git a/examples/resources/6-circle-schematic.png b/docs/source/examples/notebooks/resources/6-circle-schematic.png similarity index 100% rename from examples/resources/6-circle-schematic.png rename to docs/source/examples/notebooks/resources/6-circle-schematic.png diff --git a/examples/resources/LNO_LAO_s14.dat b/docs/source/examples/notebooks/resources/LNO_LAO_s14.dat similarity index 100% rename from examples/resources/LNO_LAO_s14.dat rename to docs/source/examples/notebooks/resources/LNO_LAO_s14.dat diff --git a/examples/resources/img69.gif b/docs/source/examples/notebooks/resources/img69.gif similarity index 100% rename from examples/resources/img69.gif rename to docs/source/examples/notebooks/resources/img69.gif diff --git a/examples/resources/k4cv.png b/docs/source/examples/notebooks/resources/k4cv.png similarity index 100% rename from examples/resources/k4cv.png rename to docs/source/examples/notebooks/resources/k4cv.png diff --git a/examples/tst_UB_in_descriptor_document.ipynb b/docs/source/examples/notebooks/tst_UB_in_descriptor_document.ipynb similarity index 100% rename from examples/tst_UB_in_descriptor_document.ipynb rename to docs/source/examples/notebooks/tst_UB_in_descriptor_document.ipynb diff --git a/examples/tst_UB_in_stream.ipynb b/docs/source/examples/notebooks/tst_UB_in_stream.ipynb similarity index 100% rename from examples/tst_UB_in_stream.ipynb rename to docs/source/examples/notebooks/tst_UB_in_stream.ipynb diff --git a/examples/tst_e4cv_fourc.ipynb b/docs/source/examples/notebooks/tst_e4cv_fourc.ipynb similarity index 99% rename from examples/tst_e4cv_fourc.ipynb rename to docs/source/examples/notebooks/tst_e4cv_fourc.ipynb index 1f8fc4f5..56c86379 100644 --- a/examples/tst_e4cv_fourc.ipynb +++ b/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" ] }, { diff --git a/examples/tst_e6c_test_calculations.ipynb b/docs/source/examples/notebooks/tst_e6c_test_calculations.ipynb similarity index 98% rename from examples/tst_e6c_test_calculations.ipynb rename to docs/source/examples/notebooks/tst_e6c_test_calculations.ipynb index b8fffe5f..db4c4ab9 100644 --- a/examples/tst_e6c_test_calculations.ipynb +++ b/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 -} \ No newline at end of file +} diff --git a/examples/var_e4cv_renamed_axes.ipynb b/docs/source/examples/notebooks/var_e4cv_renamed_axes.ipynb similarity index 99% rename from examples/var_e4cv_renamed_axes.ipynb rename to docs/source/examples/notebooks/var_e4cv_renamed_axes.ipynb index eadf65b1..7dc2c01f 100644 --- a/examples/var_e4cv_renamed_axes.ipynb +++ b/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" ] }, { diff --git a/examples/var_engines.ipynb b/docs/source/examples/notebooks/var_engines.ipynb similarity index 100% rename from examples/var_engines.ipynb rename to docs/source/examples/notebooks/var_engines.ipynb diff --git a/examples/var_nslsii_tardis.ipynb b/docs/source/examples/notebooks/var_nslsii_tardis.ipynb similarity index 100% rename from examples/var_nslsii_tardis.ipynb rename to docs/source/examples/notebooks/var_nslsii_tardis.ipynb diff --git a/env-dev.yml b/env-dev.yml index 8494592b..7a18abe1 100644 --- a/env-dev.yml +++ b/env-dev.yml @@ -20,6 +20,7 @@ dependencies: - hkl - ipython - jupyter + - nbsphinx - numpy - ophyd - packaging diff --git a/examples/Makefile b/examples/Makefile deleted file mode 100644 index 5977bf9e..00000000 --- a/examples/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -# 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 $< diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 62a1bc9b..00000000 --- a/examples/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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/examples/geo_e4cv.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/geo_e6c.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/geo_k4cv.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/how_additional_parameters.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/how_extra_real_axis.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/tst_e4cv_fourc.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/tst_e6c_test_calculations.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/tst_UB_in_descriptor_document.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/var_e4cv_renamed_axes.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/var_engines.ipynb -* https://nbviewer.jupyter.org/github/bluesky/hklpy/blob/main/examples/var_nslsii_tardis.ipynb