Notebooks (#656)

ufs-community · Nov 20, 2024 · 8ab5515 · 8ab5515
1 parent db80f2c
commit 8ab5515
Show file tree

Hide file tree

Showing 57 changed files with 6,282 additions and 2 deletions.
diff --git a/.github/scripts/test.sh b/.github/scripts/test.sh
@@ -8,11 +8,12 @@ run_tests() {
   devpkgs=$(jq .packages.dev[] recipe/meta.json | tr -d ' "')
   conda create --yes --name $env --quiet python=$PYTHON_VERSION $devpkgs
   conda activate $env
+  . notebooks/install-deps
   set -x
   python --version
   git clean -dfx
   pip install --editable src # sets new Python version in entry-point scripts
-  make test
+  make test && make test-nb
   status=$?
   set +x
   conda deactivate

diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 CHANNELS  = $(addprefix -c ,$(shell tr '\n' ' ' <$(RECIPE_DIR)/channels)) -c local
 METADEPS  = $(addprefix $(RECIPE_DIR)/,meta.yaml) src/uwtools/resources/info.json
 METAJSON  = $(RECIPE_DIR)/meta.json
-TARGETS   = clean-devenv devshell docs env format lint meta package test typecheck unittest
+TARGETS   = clean-devenv devshell docs env format lint meta package test test-nb typecheck unittest
 
 export RECIPE_DIR := $(shell cd ./recipe && pwd)
 
@@ -41,6 +41,9 @@ package: meta
 test:
 	recipe/run_test.sh
 
+test-nb:
+	$(MAKE) -C notebooks test-nb
+
 typecheck:
 	recipe/run_test.sh typecheck
 

diff --git a/binder/environment.yml b/binder/environment.yml
@@ -0,0 +1,6 @@
+name: default
+channels:
+  - conda-forge
+  - ufs-community
+dependencies:
+  - uwtools
diff --git a/docs/sections/user_guide/api/config.rst b/docs/sections/user_guide/api/config.rst
@@ -1,6 +1,9 @@
 ``uwtools.api.config``
 ======================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Fconfig.ipynb
+
 .. automodule:: uwtools.api.config
    :inherited-members: UserDict
    :members:
diff --git a/docs/sections/user_guide/api/fs.rst b/docs/sections/user_guide/api/fs.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.fs``
 ==================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Ffs.ipynb
+
 .. automodule:: uwtools.api.fs
    :members:
diff --git a/docs/sections/user_guide/api/rocoto.rst b/docs/sections/user_guide/api/rocoto.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.rocoto``
 ======================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Frocoto.ipynb
+
 .. automodule:: uwtools.api.rocoto
    :members:
diff --git a/docs/sections/user_guide/api/template.rst b/docs/sections/user_guide/api/template.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.template``
 ========================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Ftemplate.ipynb
+
 .. automodule:: uwtools.api.template
    :members:
diff --git a/docs/sections/user_guide/index.rst b/docs/sections/user_guide/index.rst
@@ -8,3 +8,5 @@ User Guide
    cli/index
    api/index
    yaml/index
+
+.. include:: /shared/binder_links.rst
diff --git a/docs/shared/binder_links.rst b/docs/shared/binder_links.rst
@@ -0,0 +1,13 @@
+Jupyter Notebooks
+-----------------
+
+* Jupyter Notebook Tutorials (API)
+
+   * `Config Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Fconfig.ipynb>`_
+   * `File System Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Ffs.ipynb>`_
+   * `Rocoto Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Frocoto.ipynb>`_
+   * `Template Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Ftemplate.ipynb>`_
+
+* Cookbooks
+
+   * `Configuring an Experiment with UW Tools <https://mybinder.org/v2/gh/ufs-community/uwtools/notebooks?labpath=notebooks%2Fexp-config-cb.ipynb>`_
diff --git a/notebooks/.gitignore b/notebooks/.gitignore
@@ -0,0 +1,2 @@
+.ipynb_checkpoints
+tmp
diff --git a/notebooks/Makefile b/notebooks/Makefile
@@ -0,0 +1,18 @@
+TARGETS = format lint test-nb unittest
+
+.PHONY: $(TARGETS)
+
+all:
+	$(error Valid targets are: $(TARGETS))
+
+format:
+	black tests
+	isort tests
+
+lint:
+	pylint tests
+
+test-nb: lint unittest
+
+unittest:
+	pytest tests