Merge branch 'add-notebooks' into 'main'

Add example notebooks to hyswap repository

See merge request water/computational-tools/surface-water-work/hyswap!79

.gitlab-ci.yml

@@ -25,6 +25,7 @@ Test and Lint:
  - apt-get install -y xdg-utils
  - apt-get install -y lynx
  - apt-get install -y graphviz
+ - apt-get install -y pandoc
  - python -m pip install --upgrade pip
  - pip install -r requirements.txt
  - pip install -r requirements-dev.txt

README.md

@@ -75,6 +75,9 @@ To run the linting and formatting checks locally, run the following commands fro
 flake8 .
 pydocstringformatter .
 ```
+### Running the Example Workflow Notebooks
+
+The example workflow notebooks are extended example use cases of `hyswap` functions. Open the jupyter notebooks from the 'example_notebooks' folder in the `hyswap` repository. The notebooks sometimes utilize additional packages that are not required to run `hyswap`. You can use the developer installation instructions to ensure you have all of the required packages to run the notebooks. 
 
 ## Contributing
 

docs/source/conf.py

@@ -31,9 +31,14 @@
  'sphinx.ext.coverage',
  'sphinx.ext.viewcode',
  'matplotlib.sphinxext.plot_directive',
- 'sphinx.ext.githubpages'
+ 'sphinx.ext.githubpages',
+ 'nbsphinx',
+ 'nbsphinx_link'
 ]
 
+# allow errors to occur in notebooks
+# nbsphinx_allow_errors = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -96,8 +101,13 @@
 from hyswap import runoff
 import numpy as np
 import pandas as pd
+import geopandas
 import matplotlib.pyplot as plt
 import dataretrieval
+from pynhd import WaterData
+import warnings
+from datetime import datetime, timedelta
+from tqdm import tqdm
 '''
 
 # mpl plots - metadata for the documentation plots
@@ -117,7 +127,7 @@
 # The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 
-html_theme = 'bizstyle'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further. For a list of options available for each theme, see the
@@ -136,10 +146,12 @@
 
 # Links to not "check" because they are problematic for the link checker
 # typically DOI links don't work
+# Last one does not yet exist
 linkcheck_ignore = [
  r'https://doi.org/10.3133/wsp1542A',
  r'https://doi.org/10.1029/2022WR031930',
  r'https://pypi.org/project/hyswap/',
+ r'https://github.com/DOI-USGS/hyswap/tree/main/example_notebooks',
  r'https://doi.org/10.1098/rsta.2019.0431',
  r'https://doi.org/10.1111/j.1752-1688.2011.00578.x',
  r'https://doi.org/10.3133/tm11A3',

docs/source/examples/cumulative_hydrograph_examples.rst

@@ -148,7 +148,7 @@ We provide an example of doing this by filling between the 10th and 90th percent
  # plot the cumulative streamflow hydrograph
  fig, ax = plt.subplots(figsize=(8, 5))
  ax = hyswap.plots.plot_cumulative_hydrograph(
- df, data_column_name='00060_Mean',
- 2021, envelope_pct=[10, 90], color='red', alpha=0.25,
+ df, 2021, data_column_name='00060_Mean',
+ envelope_pct=[10, 90], color='red', alpha=0.25,
  ax=ax, title='Cumulative Streamflow Hydrograph')
  plt.show()