Merge pull request #114 from aleaf/aleaf-html-docs

Feat: HTML/GitHub pages version of curriculum

.github/workflows/build_docs.yaml

@@ -0,0 +1,81 @@
+# from pyproj: https://github.com/pyproj4/pyproj/blob/master/.github/workflows/build_docs.yaml
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+      - '*docs*'
+  release:
+    types: [ created ]
+  workflow_dispatch:
+
+jobs:
+  docs:
+    name: Publish Docs
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+
+    - name: Fetch all Git tags
+      run: git fetch --prune --unshallow --tags
+
+    - name: Setup Micromamba
+      uses: mamba-org/setup-micromamba@v1
+      with:
+        environment-file: docs/docs-environment.yml
+        cache-environment: false
+        cache-downloads: false
+
+    - name: Conda info
+      shell: bash -l {0}
+      run: micromamba info
+    - name: Install Modflow executables
+      uses: modflowpy/install-modflow-action@v1
+      with:
+        path: ~/.local/bin
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+    - name: Modflow version
+      shell: bash -l {0}
+      run: mf6 --version
+    - name: Install ipykernel
+      shell: bash -l {0}
+      run: |
+        python -m ipykernel install --user --name pyclass --display-name "pyclass"
+    - name: Conda list
+      shell: bash -l {0}
+      run: micromamba list
+    - name: Run tests
+      shell: bash -l {0}
+      run: |
+        pytest tests/test_notebook_output.py
+
+    - name: Build docs
+      shell: bash -l {0}
+      run: |
+        set -e
+        make -C docs html
+
+    - name: Deploy 🚀
+      uses: JamesIves/[email protected]
+      if: ${{ github.event_name == 'release' }}
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BRANCH: gh-pages
+        FOLDER: docs/build/html
+        CLEAN: false
+        TARGET_FOLDER: ${{ github.ref }}
+
+    - name: Deploy 🚀
+      uses: JamesIves/[email protected]
+      if: ${{ github.event_name == 'push' }}
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BRANCH: gh-pages
+        FOLDER: docs/build/html
+        CLEAN: false
+        TARGET_FOLDER: latest

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+#SPHINXOPTS    = "-W"  # This flag turns warnings into errors.
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = PackagingScientificPython
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/docs-environment.yml

@@ -0,0 +1,53 @@
+name: pyclass-docs
+channels:
+  - conda-forge
+dependencies:
+  # required
+  - python=3.11
+  - pip
+
+  - numpy
+  - matplotlib
+
+  - jupyter
+  - jupytext
+  - jupyterlab
+  - git
+  - python-dateutil
+  - affine
+  - scipy
+  - openpyxl
+  - xlrd
+  - pandas
+  - netcdf4
+  - pyshp
+  - rasterio
+  - rasterstats
+  - fiona
+  - descartes
+  - pyproj
+  - shapely
+  - geos
+  - geojson
+  - geopandas
+  - vtk
+  - xarray
+  - rioxarray
+  - uxarray
+  - pyyaml
+  - rtree
+  - requests
+  - pytest
+  - statsmodels
+  - dataretrieval
+  - flopy
+  - gis-utils
+  - sfrmaker
+  - modflow-export
+  - modflow-setup
+  - sphinx
+  - numpydoc
+  - nbsphinx  # for rendering notebooks in sphinx-generated docs
+  - sphinx-copybutton
+  - sphinx_rtd_theme
+  - myst-parser  # for including markdown source

docs/source/SOME_HELPFUL_LINKS.md

@@ -0,0 +1,48 @@
+# Here are some links you might find helpful moving forward with python
+
+### conda
+* [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)
+* [General information on conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html)
+* [Managing Conda Environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+* [Tutorial introduction to conda enviroments](https://towardsdatascience.com/getting-started-with-python-environments-using-conda-32e9f2779307)
+* [Conda-pack](https://conda.github.io/conda-pack/)
+
+### cheat sheets
+* [conda](https://conda.io/projects/conda/en/latest/user-guide/cheatsheet.html)
+* [pandas](https://pandas.pydata.org/Pandas_Cheat_Sheet.pdf)
+* [numpy](http://datacamp-community-prod.s3.amazonaws.com/ba1fe95a-8b70-4d2f-95b0-bc954e9071b0)
+* [data science packages](https://www.utc.fr/~jlaforet/Suppl/python-cheatsheets.pdf)
+* [Jupyter Notebook/Lab keyboard shortcuts](https://towardsdatascience.com/jypyter-notebook-shortcuts-bf0101a98330)
+* [Numpy for MATLAB Users](https://numpy.org/doc/stable/user/numpy-for-matlab-users.html)
+
+### general python
+* [Tutorial on General Python Programming](https://cscircles.cemc.uwaterloo.ca/)
+* [Installing packages dynamically into an environment](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#working-in-development-mode)
+
+### Flopy and MODFLOW
+* [Flopy code](https://github.com/modflowpy/flopy.git)
+* [Flopy official documentation](https://flopy.readthedocs.io/en/3.3.5/)
+* [MODFLOW 6 -- online documentation](https://modflow6.readthedocs.io/en/latest/)
+* [MODFLOW 6 Example Problems -- overview](https://modflow6-examples.readthedocs.io/en/master/introduction.html)
+* [MODFLOW 6 Example Problems](https://modflow6-examples.readthedocs.io/en/master/examples.html)
+* [Flopy Tutorial Notebooks](https://github.com/modflowpy/flopy/blob/develop/docs/notebook_examples.md)
+* [Groundwater Paper](https://ngwa.onlinelibrary.wiley.com/doi/abs/10.1111/gwat.12413)
+* [Another Groundwater Paper](https://ngwa.onlinelibrary.wiley.com/doi/10.1111/gwat.13259)
+
+### Modflow-setup and SFRmaker
+* [Modflow-setup code and docs](https://github.com/doi-usgs/modflow-setup)
+* [Modflow-setup paper](https://www.frontiersin.org/articles/10.3389/feart.2022.903965/full)
+* [SFRmaker code and docs](https://github.com/DOI-USGS/sfrmaker)
+* [SFRmaker paper](https://ngwa.onlinelibrary.wiley.com/doi/10.1111/gwat.13095)
+* [A worked example/workflow using Modflow-setup, SFRmaker, and PEST++](https://github.com/DOI-USGS/neversink_workflow)
+* [A worked example/workflow Groundwater paper](https://ngwa.onlinelibrary.wiley.com/doi/full/10.1111/gwat.13129)
+
+### some galleries
+* [matplotlib gallery](https://matplotlib.org/stable/gallery/index.html)
+* [geopandas gallery](https://geopandas.org/en/stable/gallery/index.html)
+* [a hydrologic "data story" using pandas](https://code.usgs.gov/cdi/cdi-fy20/jupyter-data-stories/-/tree/main/examples/hydrologic_data_analysis)
+
+### more general references
+* [numpy for matlab users](https://numpy.org/doc/stable/user/numpy-for-matlab-users.html)
+* [datetime formats](https://docs.python.org/3/library/datetime.html) (jump to the bottom of the page where it says "Format Codes")
+* [Jupyter Lab Getting Started](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html)

docs/source/bonus_examples.rst

@@ -0,0 +1,6 @@
+Bonus examples
+=======================================
+
+.. nbgallery::
+
+   notebooks/part0_python_intro/09_Geopandas_ABQ.ipynb