Merge branch 'main' into gis_io

USEPA · Jun 13, 2024 · b4162af · b4162af
2 parents b3d9563 + cd9290c
commit b4162af
Show file tree

Hide file tree

Showing 151 changed files with 24,064 additions and 1,371 deletions.
diff --git a/.github/workflows/build_deploy_pages.yml b/.github/workflows/build_deploy_pages.yml
@@ -21,7 +21,7 @@ jobs:
           git remote -v
       - uses: actions/setup-python@v2
         with: 
-          python-version: '3.8'
+          python-version: '3.11'
       - name: Install package
         run: |
           pip install -e .

diff --git a/.github/workflows/build_tests.yml b/.github/workflows/build_tests.yml
@@ -8,14 +8,16 @@ on:
     branches: [ main, dev ]
   pull_request:
     branches: [ main, dev ]
+  schedule:
+    - cron: '0 0 1 * *'
 
 jobs:
 
   build:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest] 
     steps:
     - uses: actions/checkout@v2
@@ -39,13 +41,12 @@ jobs:
         name: wntr_${{ matrix.python-version }}_${{ matrix.os }}.whl
         path: dist/wntr*
 
-  test:
-    name: Test install and usage of wntr
+  install_import:
     needs: build
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest]    
     steps:
     - name: Set up Python 
@@ -62,17 +63,17 @@ jobs:
     - name: Install wntr
       run: |
         python -m pip install --upgrade pip
-        pip install wheel numpy scipy networkx pandas matplotlib
+        pip install wheel numpy scipy networkx pandas matplotlib setuptools
         pip install --no-index --pre --find-links=. wntr
     - name: Usage of wntr
       run: |
         python -c "import wntr"
 
-  create_coverage_reports:
+  pytest_coverage:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.7', '3.10']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest]
     steps:
     - uses: actions/checkout@v2
@@ -86,16 +87,7 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         python -m pip install -e .
-    - name: Run Tests on Windows
-      if: matrix.os == 'windows-latest'
-      run: | # the following skips windows rst doctests that rely on geopandas (gis.rst and model_io.rst) because skipif is not working properly
-        coverage erase
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest  --doctest-modules --doctest-glob="*.rst" wntr
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" --ignore-glob="*model_io.rst" --ignore-glob="*gis.rst" documentation
-      env:
-        COVERAGE_FILE: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
     - name: Run Tests
-      if: matrix.os != 'windows-latest'
       run: | 
         coverage erase
         coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest  --doctest-modules --doctest-glob="*.rst" wntr
@@ -110,13 +102,13 @@ jobs:
         path: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
 
   combine_reports:
-    needs: [ create_coverage_reports ]
+    needs: [ pytest_coverage ]
     runs-on: ubuntu-latest
     steps:
     - name: Set up Python 
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
     - uses: actions/checkout@v2
     - name: Install coverage
       run: |
@@ -155,14 +147,14 @@ jobs:
         path: htmlcov
 
   combine_reports_upload_coveralls:
-    needs: [ create_coverage_reports ]
+    needs: [ pytest_coverage ]
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
     - name: Set up Python 
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
     - uses: actions/checkout@v2
     - name: Install coverage
       run: |

diff --git a/.github/workflows/quick_check.yml b/.github/workflows/quick_check.yml
@@ -15,7 +15,7 @@ jobs:
   test:
     strategy:
       matrix:
-        python-version: ['3.8', '3.10']
+        python-version: ['3.9', '3.11']
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - name: build the sdist
         run: |
           python -m pip install --upgrade build

diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,7 @@ build/
 wntr.egg-info/
 dist/
 docker/
+/.vscode
 
 *.pyd
 *.pyc
@@ -20,3 +21,5 @@ temp*
 examples/*.inp
 wntr/tests/*.png
 
+documentation/_local
+documentation/apidoc
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <h1>
-<img src="https://raw.githubusercontent.com/usepa/wntr/main/documentation/figures/logo.jpg" width="375">
+<img src="https://raw.githubusercontent.com/usepa/wntr/main/documentation/_static/logo.jpg" width="375">
 </h1><br>
 
 [![build](https://github.com/USEPA/WNTR/workflows/build/badge.svg)](https://github.com/USEPA/WNTR/actions/workflows/build_tests.yml)

diff --git a/documentation/_static/epa_logo.png b/documentation/_static/epa_logo.png
diff --git a/documentation/figures/logo.jpg → documentation/_static/logo.jpg b/documentation/figures/logo.jpg → documentation/_static/logo.jpg
diff --git a/documentation/_static/snl_logo.png b/documentation/_static/snl_logo.png
diff --git a/documentation/_static/water_circle.jpg b/documentation/_static/water_circle.jpg
diff --git a/documentation/_static/water_drop.jpg b/documentation/_static/water_drop.jpg
diff --git a/documentation/_static/wntr-favicon.svg b/documentation/_static/wntr-favicon.svg
diff --git a/documentation/_templates/autosummary/base.rst b/documentation/_templates/autosummary/base.rst
@@ -0,0 +1,15 @@
+{% if objtype == 'property' %}
+:orphan:
+{% endif %}
+
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == 'property' %}
+property
+{% endif %}
+
+.. auto{{ objtype }}:: {{ fullname | replace(module + ".", module + "::") }}
diff --git a/documentation/_templates/autosummary/class.rst b/documentation/_templates/autosummary/class.rst
@@ -0,0 +1,37 @@
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+{% block methods %}
+{% if methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_attributes %}
+         {%- if not item.startswith('_') %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+   {% if methods or attributes %}
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   {% endif %}
diff --git a/documentation/_templates/autosummary/exception.rst b/documentation/_templates/autosummary/exception.rst
@@ -0,0 +1,34 @@
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+.. autoexception:: {{ objname }}
+   :no-inherited-members:
+
+{% block methods %}
+{% if methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_attributes %}
+         {%- if not item.startswith('_') %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/documentation/_templates/autosummary/module.rst b/documentation/_templates/autosummary/module.rst
@@ -0,0 +1,73 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :exclude-members: {% for item in attributes %}{{ item }}, {% endfor %}{% for item in functions %}{{ item }}, {% endfor %}{% for item in classes %}{{ item }}, {% endfor %}{% for item in exceptions %}{{ item }}, {% endfor %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/base.rst
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/base.rst
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/exception.rst
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+   :template: autosummary/module.rst
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/documentation/acknowledgements.rst b/documentation/acknowledgements.rst
@@ -3,7 +3,7 @@
     \clearpage
 
 Acknowledgements
-======================================
+================
 
 WNTR is developed through a collaboration between U.S. Environmental Protection Agency, Sandia National
 Laboratories, and the open-source community. The U.S. Environmental Protection Agency acknowledges the