EMCPy V2

.github/workflows/documentation.yaml

@@ -1,53 +1,44 @@
-name: Deploy documentation
+name: Build & Deploy Docs
+
 on:
   push:
-    branches:
-      - develop
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+  workflow_dispatch: {}
+
 permissions:
-    contents: write
+  contents: write
+
 jobs:
-  docs:
+  build-deploy:
     runs-on: ubuntu-latest
     steps:
-      # Setup Python
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+        with: { lfs: true }
+      - uses: actions/setup-python@v5
         with:
-          python-version: 3.10.10
+          python-version: '3.11'
+          cache: 'pip'
 
-      # Update conda
-      - name: Update conda
-        run: conda update -n base -c defaults conda
+      - name: Upgrade pip/wheel/setuptools
+        run: python -m pip install -U pip wheel setuptools
 
-      # Intall pip
-      - name: Install pip
-        run: conda install pip
+#      - name: Install docs deps
+#        run: |
+#          python -m pip install --upgrade pip
+#          pip install -r docs/requirements.txt
 
-      # Install cartopy
-      - name: Install cartopy
-        run: conda install -c conda-forge cartopy
+      - name: Install package with docs extras
+        run: pip install .[docs]
 
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          lfs: true
-
-      # Install emcpy
-      - name: Upgrade pip
-        run: $CONDA/bin/pip3 install --upgrade pip
-      - name: Install emcpy and dependencies
-        run: |
-          $CONDA/bin/pip3 install --use-deprecated=legacy-resolver -r requirements-github.txt --user .
-          echo "$PWD"
-
-      # Build docs
-      - name: Sphinx build
-        run: |
-          sphinx-build docs _build
-      - name: Deploy
+      - name: Build docs (fail on warnings)
+        run: sphinx-build -b html -W -q docs _build/html
+
+      - name: Deploy to gh-pages
+        if: github.event_name == 'push'
         uses: peaceiris/actions-gh-pages@v3
         with:
-          publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: _build/
-          force_orphan: true
+          publish_branch: gh-pages
+          publish_dir: _build/html

.github/workflows/tests.yaml

@@ -4,43 +4,34 @@ on: [push, pull_request]
 jobs:
   run_pytests:
     runs-on: ubuntu-latest
-    name: Install and run tests with pytests
 
     steps:
-
-    # Setup Python
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v2
-      with:
-        python-version: 3.10.10
-
-    # Update conda
-    - name: Update conda
-      run: conda update -n base -c defaults conda
-
-    # Intall pip
-    - name: Install pip
-      run: conda install pip
-
-    # Install cartopy
-    - name: Install cartopy
-      run: conda install -c conda-forge cartopy
-
-    - name: Checkout
-      uses: actions/checkout@v3
-      with:
-        lfs: true
-
-    # Install emcpy
-    #- name: Upgrade pip
-    #  run: $CONDA/bin/pip3 install --upgrade pip
-    - name: Install emcpy and dependencies
-      run: |
-        $CONDA/bin/pip3 install --use-deprecated=legacy-resolver -r requirements-github.txt --user .
-        echo "$PWD" 
-
-    # Run empcy test suite
-    - name: Run emcpy pytests
-      run: |
-        cd $GITHUB_WORKSPACE
-        pytest -v src/tests
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Upgrade pip and install deps (wheel-only)
+        run: |
+          python -m pip install --upgrade pip wheel
+          # If you want to be strict about wheels only, keep --only-binary
+          python -m pip install --only-binary=:all: \
+            numpy scipy matplotlib pytest \
+            shapely pyproj cartopy
+          python -m pip install -r requirements-github.txt
+          python -m pip install -e .
+          python - <<'PY'
+          import cartopy, shapely, pyproj
+          print("cartopy", cartopy.__version__)
+          print("shapely", shapely.__version__)
+          print("pyproj", pyproj.__version__)
+          PY
+
+      - name: Run pytest
+        env:
+          MPLBACKEND: Agg
+        run: pytest -q

.gitignore

@@ -76,6 +76,7 @@ target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
+docs/.ipynb_checkpoints/
 
 # IPython
 profile_default/

MANIFEST.in

@@ -1,2 +1,7 @@
-include package/*.yaml
-recursive-include src *.yaml *.py *.png
+include LICENSE
+include README.md
+
+recursive-include docs *.md *.rst *.png *.svg *.jpg *.gif *.ico
+recursive-include src/emcpy *.py *.typed
+
+global-exclude *.py[cod] __pycache__ *.so *.dylib *.dll

README.md

@@ -1,17 +1,58 @@
-# emcpy
-EMC python tools and utilities
-
-### Installation
-```sh
-$> git clone https://github.com/noaa-emc/emcpy
-$> cd emcpy
-$> pip install .
+# EMCPy
+
+[![CI](https://github.com/NOAA-EMC/emcpy/actions/workflows/ci.yml/badge.svg)](https://github.com/NOAA-EMC/emcpy/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://noaa-emc.github.io/emcpy/)
+
+**EMCPy** (Environmental Modeling Center Python utilities) provides tools for visualization, diagnostics, and analysis in support of NOAA’s Environmental Modeling Center (EMC) workflows. It offers a lightweight, extensible framework for building plots, handling data fields, and automating workflows used in EMC’s operational and research environments.
+
+---
+
+## Features
+
+- **Plotting utilities**
+  - High-level wrappers around Matplotlib and Cartopy
+  - Support for discrete fields, colorbars, and meteorological conventions
+  - Ready-to-use plot layers: scatter, gridded fields, contour, violin, box-and-whisker, error bars, and more
+
+- **Consistent interfaces**
+  - Unified API for building figures and subplots
+  - Clear separation of plot layers, figure creation, and feature controls
+
+- **Documentation and examples**
+  - [Gallery of plot types](https://noaa-emc.github.io/emcpy/galleries/plot_types)
+  - Explanations of design choices, discrete fields, and troubleshooting
+
+---
+
+## Installation
+
+```bash
+pip install emcpy
 ```
 
-### Documentation
-Documentation is automatically generated when `develop` is updated and available [here](https://noaa-emc.github.io/emcpy/).
+For the latest development version:
 
-To manually generate documentation upon installation (requires [`pdoc`](https://pdoc.dev/)):
-```sh
-$> pdoc --docformat "google" emcpy
+```bash
+git clone https://github.com/NOAA-EMC/emcpy.git
+cd emcpy
+pip install -e .[dev,test,docs]
 ```
+
+---
+
+## Documentation
+
+Full documentation is available here:  
+👉 [https://noaa-emc.github.io/emcpy/](https://noaa-emc.github.io/emcpy/)
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on [GitHub](https://github.com/NOAA-EMC/emcpy).
+
+---
+
+## License
+
+This project is licensed under the **LGPL v2.1 or later**. See the [LICENSE](LICENSE) file for details.

docs/_static/css/extra.css

@@ -0,0 +1,33 @@
+/* docs/_static/css/extra.css */
+
+/* Hide filename under each thumbnail */
+.sphx-glr-thumbcontainer .sphx-glr-thumbnail-subtitle {
+  display: none !important;
+}
+
+/* Allow titles to wrap to two lines, then ellipsis */
+.sphx-glr-thumbcontainer .sphx-glr-thumbnail-title {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;       /* show up to 2 lines */
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  line-height: 1.25;
+  min-height: 2.6em;           /* keep tile heights consistent */
+  margin-top: 0.35rem;
+}
+
+/* Optional: tighten grid and enforce a comfortable tile width */
+.sphx-glr-thumbcontainer {
+  width: 280px;                /* or 300px if you want wider tiles */
+  max-width: 100%;
+}
+.sphx-glr-thumbcontainer img {
+  display: block;
+  margin: 0 auto;
+}
+
+/* Safety: make sure thumbnails remain clickable */
+.sphx-glr-thumbcontainer a {
+  display: block;
+  pointer-events: auto;
+}