Add documentation for using Jupyter notebooks (#1155)

* Remove unneeded notebook tests reqs and move scipy to parameter_sweep

* Remove requirement for Python<3.8 backport

* Create notebooks extras_require target and add it to requirements-dev

* Add first version of Jupyter notebooks docs

* Fix grammar

* Add document to index

* Fix spacing issue in code blocks

* Fix auto-numbered list

docs/getting_started.rst

@@ -132,6 +132,8 @@ Then, run the following command to run the complete WaterTAP test suite:
 
 .. note:: Some tests will be skipped (denoted by an ``s`` symbol). This is to be expected, as some of the tests are only applicable within a developer environment.
 
+.. _install-dev:
+
 For WaterTAP developers
 -----------------------
 
@@ -176,3 +178,8 @@ To verify that the installation was successful, try running the WaterTAP test su
    pytest
 
 To view/change the generated documentation, see the :ref:`documentation-mini-guide` section.
+
+Using Jupyter notebooks
+-----------------------
+
+WaterTAP has several examples and tutorials provided as Jupyter notebooks. Additional steps might be required (in addition to the WaterTAP standard installation described above); see :ref:`notebooks` for instructions.

docs/how_to_guides/index.rst

@@ -24,3 +24,4 @@ How To Guides
    how_to_use_EDB
    how_to_use_ui_api
    how_to_contribute_development
+   notebooks

docs/how_to_guides/notebooks.rst

@@ -0,0 +1,34 @@
+.. _notebooks:
+
+How to run WaterTAP with Jupyter notebooks
+==========================================
+
+This guide describes the supported methods to work with WaterTAP using Jupyter notebooks.
+
+Local (developer) installation
+------------------------------
+
+.. important:: These instructions assume that a WaterTAP developer environment has already been configured, as described in e.g. :ref:`install-dev`.
+
+#. Activate your WaterTAP environment. If your environment has a name different from ``watertap-dev``, replace ``watertap-dev`` with the actual name wherever applicable:
+
+   .. code-block:: shell
+
+      conda activate watertap-dev
+
+#. Navigate to the directory where your local clone of the WaterTAP repository is located
+
+#. Run the following command to register the currently active WaterTAP environment as a Jupyter kernel. This will create a dedicated WaterTAP kernel that's selectable in the Jupyter web interface, ensuring that the notebook code is run in the correct Python environment where WaterTAP is available.
+
+   .. code-block:: shell
+
+      python -m ipykernel --user --name "watertap-dev"
+
+#. Then, start the Jupyter server from the current directory, navigate to the desired notebook using the file browser, and launch it
+
+#. If prompted to select a kernel, select ``watertap-dev`` from the menu. Otherwise, ensure ``watertap-dev`` appears in the kernel box in the top-right corner of the notebook interface
+
+Online using Binder.org
+-----------------------
+
+(Coming soon)

requirements-dev.txt

@@ -4,4 +4,4 @@ pre-commit
 pylint
 astroid
 # Defer to setup.py contents
--e .[dev]
+-e .[dev,notebooks]

setup.py

@@ -86,17 +86,13 @@
         "pymongo>3",  # database interface
         "fastjsonschema",  # schema validation
         "click",  # command-line tools with Click
-        # tutorial tests
-        "nbformat",
-        "scipy",
         # for parameter_sweep
         "h5py",
         "requests",
+        "scipy",
         # for watertap.ui.api_model (though may be generally useful)
         "pydantic < 2",
         "numpy",
-        # for importlib.metadata.entry_points()
-        "importlib_metadata; python_version < '3.8' ",
     ],
     extras_require={
         "testing": [
@@ -107,6 +103,10 @@
             "nbmake",
             "nbconvert",
         ],
+        "notebooks": [
+            "jupyter",
+            "ipykernel",
+        ],
         "dev": [
             "nbsphinx",  # jupyter notebook support for sphinx
             "jinja2<3.1.0",  # see watertap-org/watertap#449