Merge PR #283 (Implement several minor bug fixes)

This merge brings PR #283 (Split python packages needed for RTD documentation builds out of the GCPy conda environment and into a separate environment; remove awscli, by @yantosca) This PR removes awscli from the GCPy Mamba/Conda environment, since that prevents installation from PyPi. Also we have moved the packages that are needed to build ReadTheDocs from the GCPy environment into a separate Mamba/Conda environment. This allows us to update those packages to a more recent Python version while keeping the GCPy environment pegged at Python 3.9.18. Signed-off-by: Bob Yantosca <[email protected]>
geoschem · Feb 6, 2024 · db9064b · db9064b
2 parents fb076e2 + 9233b99
commit db9064b
Show file tree

Hide file tree

Showing 13 changed files with 187 additions and 85 deletions.
diff --git a/.github/workflows/build-gcpy-environment.yml b/.github/workflows/build-gcpy-environment.yml
@@ -25,9 +25,9 @@ jobs:
         uses: mamba-org/setup-micromamba@v1
         with:
           micromamba-version: 'latest'
-          environment-file: docs/environment_files/environment.yml
+          environment-file: docs/environment_files/gcpy_environment.yml
           init-shell: bash
-          cache-environment: true
+          cache-environment: false
           generate-run-shell: true
           post-cleanup: 'all'
       - name: Test if "import gcpy" works

diff --git a/.github/workflows/build-rtd-environment.yml b/.github/workflows/build-rtd-environment.yml
@@ -0,0 +1,37 @@
+---
+#
+# GitHub action to build the ReadTheDocs environment with micromamba
+# See: https://github.com/marketplace/actions/setup-micromamba
+#
+name: build-rtd-environment
+
+on:
+  push:
+    branches: [ "main", "dev", "dependabot/*" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main", "dev" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout the GCPy repository
+        uses: actions/checkout@v4
+      - name: Create "rtd_env" environment
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          micromamba-version: 'latest'
+          environment-file: docs/environment_files/read_the_docs_environment.yml
+          init-shell: bash
+          cache-environment: false
+          generate-run-shell: true
+          post-cleanup: 'all'
+      - name: Get version numbers of packages
+        run: |
+          python --version
+          sphinx-autobuild --version
+        shell: micromamba-shell {0}
diff --git a/.github/workflows/build-test-environment.yml b/.github/workflows/build-test-environment.yml
@@ -27,7 +27,7 @@ jobs:
           micromamba-version: 'latest'
           environment-file: docs/environment_files/testing.yml
           init-shell: bash
-          cache-environment: true
+          cache-environment: false
           generate-run-shell: true
           post-cleanup: 'all'
       - name: Test if "import gcpy" works

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,13 +13,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Badges in `docs/source/index.rst`
 - GitHub action to push GCPy releases to PyPi
 - Script `./release/changeVersionNumbers.sh`, used to update version numbers in various files before release
+- Mamba/Conda enviroment file `docs/environment_files/read_the_docs_environment.yml`, for building ReadTheDocs documentation
+- Environment files `docs/environment_files/gcpy_requirements.txt` and `docs/environment_files/read_the_docs_requirements.txt`
 
 ### Changed
 - Bump pip from 23.2.1 to 23.3 (dependabot suggested this)
 - Bump pypdf from 3.16.1 to 3.17.0 (dependabot suggested this)
 - YAML tag `operations_budget` is now `ops_budget_table` in `gcpy/benchmark/config/1yr_tt_benchmark.yml`
 - Now require `matplotlib=3.8.0` in `docs/environment_files/environment.yml` (with other pegged versions)
 - Now run the `stale` GitHub action at 00:00 UTC on the 1st of each month
+- Renamed `docs/environment_files/environment.yml` to `gcpy_environment.yml`
+- `environment.yml` links to `docs/environment_files/gcpy_environment.yml`
+- `requirements.txt` links to `docs/environment_files/requirements.txt`
+- Python packages for RTD documenation builds from `docs/environment_files/environment.yml`
 
 ### Fixed
 - CS inquiry functions in `gcpy/cstools.py` now work properly for `xr.Dataset` and `xr.DataArray` objects
@@ -34,6 +40,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Example script `gcpy/examples/plotting/mda8_o3_timeseries.py`
 - Removed `Pylint` GitHub action
 
+### Removed
+- Environment file `docs/environment_files/environment.yml`
+- Environment file `docs/environment_files/requirements.txt`
+- Removed `awscli` from the GCPy environment; version 2 is no longer available on conda-forge or PyPi
+
 ## [1.4.2] - 2024-01-26
 ### Added
 - Example script `create_test_plot.py`, which can be used to check that GCPy has been installed properly
@@ -42,7 +53,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - GitHub action `build-test-environment` to test the environment specified in `testing.yml`
 
 ### Changed
-- `build-gcpy-environment` GitHub action now runs with several Python versions 
+- `build-gcpy-environment` GitHub action now runs with several Python versions
 
 ### Fixed
 - Prevent overwriting of the `results` variable when parallel plotting is deactivated (`n_cores: 1`)

diff --git a/docs/environment_files/README.md b/docs/environment_files/README.md
@@ -0,0 +1,50 @@
+# Environment files
+
+This folder contains environment files that are used to install dependencies for GCPy and the ReadTheDocs documentation.
+
+NOTE: Most users will install GCPy with:
+
+```console
+$ pip install geoschem-gcpy
+```
+but GCPy developers may need to install the dependencies separately using the environment files in this folder.
+
+## Installing GCPy dependencies
+
+### With Mamba or Conda
+
+Use one of these commands to build a Mamba/Conda environment with all of the GCPy dependencies.
+
+```console
+$ mamba env create -n gcpy_env --file=gcpy_environment.yml
+```
+or
+```console
+$ conda env create -n gcpy_env --file=gcpy_environment.yml
+```
+
+### With pip
+Or use this command to install the dependencies from PyPI:
+```console
+$ pip install -r gcpy_requirements.txt
+```
+
+## Installing ReadTheDocs dependencies
+
+### With Mamba or Conda
+
+Use one of these commands to build a Mamba/Conda environment with the dependencies for building the GCPy ReadTheDocs documentation:
+
+```console
+$ mamba env create -n rtd_env --file=read_the_docs_environment.yml
+```
+or
+```console
+$ conda env create -n rtd_env --file=read_the_docs_environment.yml
+```
+
+### With pip
+Or use this command to install the dependencies from PyPi:
+```console
+$ pip install -r read_the_docs_requirements.txt
+```
diff --git a/docs/environment_files/environment.yml → docs/environment_files/gcpy_environment.yml b/docs/environment_files/environment.yml → docs/environment_files/gcpy_environment.yml
@@ -2,18 +2,19 @@
 # ======================================================================
 # GCPy environment file
 #
-# Recommended installation: with Mambaforge
+# If you wish to build a Mamba/Conda environment with the dependencies
+# for GCPy, use this command:
+#
 # $ mamba env create -n gcpy_env --file=/path/to/gcpy/environment.yml
 #
 # These package versions have been proven to work together.
 # See: https://github.com/geoschem/gcpy/issues/284
-# ======================================================================
+# =====================================================================
 name: gcpy_env
 channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - awscli==2.13.39                 # Utilities for AWS cloud
   - cartopy==0.22.0                 # Geospatial data processing
   - cf_xarray==0.8.4                # CF conventions for xarray
   - dask==2023.9.2                  # Parallel library; backend for xarray
@@ -29,9 +30,8 @@ dependencies:
   - pip==23.3                       # Install packages from PyPi
   - pylint==2.17.5                  # Python linter
   - pyproj==3.6.1                   # Python map projections library
-  - python==3.9.18                  # Any python version prior to 3.10
+  - python==3.9.18                  # Python language
   - pypdf==3.17.0                   # PDF utilities (bookmarks, etc.)
-  - recommonmark==0.7.1             # Dependency for Sphinx
   - requests==2.31.0                # HTTP library
   - scipy==1.11.2                   # Scientific python package
   - sparselt==0.1.3                 # Regridding earth system model data
@@ -41,10 +41,3 @@ dependencies:
   - esmf==8.1.1                     # Earth system modeling framework
   - esmpy==8.1.1                    # Python wrapper for ESMF
   - xesmf==0.5.1                    # Universal regridder
-  - docutils==0.16                  # Convert text to other formats
-  - jinja2==3.0.3                   # Dependency for Sphinx
-  - sphinx==3.5.4                   # Generate ReadTheDocs output
-  - sphinx-autoapi==1.9.0           # Sphinx autodoc style documentation
-  - sphinx-autobuild==2021.3.14     # Build ReadTheDos live in browser
-  - sphinxcontrib-bibtex==2.2.0     # ReadTheDocs bibliography style
-  - sphinx_rtd_theme==0.5.2         # ReadTheDocs HTML theme files
diff --git a/docs/environment_files/gcpy_requirements.txt b/docs/environment_files/gcpy_requirements.txt
@@ -0,0 +1,36 @@
+# ======================================================================
+# ReadTheDocs requirements file
+#
+# If you wish to install the dependencies for GCPy from PyPI, use:
+#
+# $ pip install -r gcpy_requirements.txt
+#
+# These package versions have been proven to work together.
+# See: https://github.com/geoschem/gcpy/issues/284
+# ======================================================================
+cartopy==0.22.0                 # Geospatial data processing
+cf_xarray==0.8.4                # CF conventions for xarray
+dask==2023.9.2                  # Parallel library; backend for xarray
+gridspec==0.1.0                 # Define Earth System Model grids
+ipython==8.15.0                 # Interactive Python (used by Jupyter)
+joblib==1.3.2                   # Parallelize python code
+jupyter==1.0.0                  # Jupyter Notebook
+matplotlib==3.8.0               # Creates plots and visualizations
+netcdf4==1.6.0                  # Python wrapper for netCDF
+netcdf-fortran==4.5.4           # Python wrapper for netCDF-Fortran
+numpy==1.26.0                   # Optimized mathematical functions
+pandas==2.1.1                   # Tables/timeseries manipulation
+pip==23.3                       # Install packages from PyPi
+pylint==2.17.5                  # Python linter
+pyproj==3.6.1                   # Python map projections library
+python==3.9.18                  # Python language
+pypdf==3.17.0                   # PDF utilities (bookmarks, etc.)
+requests==2.31.0                # HTTP library
+scipy==1.11.2                   # Scientific python package
+sparselt==0.1.3                 # Regridding earth system model data
+tabulate==0.9.0                 # Pretty-printing for column data
+tk==8.6.12                      # Tcl/tk library
+xarray==2023.8.0                # Read data from netCDF etc files
+esmf==8.1.1                     # Earth system modeling framework
+esmpy==8.1.1                    # Python wrapper for ESMF
+xesmf==0.5.1                    # Universal regridder
diff --git a/docs/environment_files/read_the_docs_environment.yml b/docs/environment_files/read_the_docs_environment.yml
@@ -0,0 +1,24 @@
+---
+# ======================================================================
+# ReadTheDocs environment file
+#
+# If you wish to build a Mamba/Conda environment with the dependencies
+# needed for building the ReadTheDocs documentation, use:
+#
+# $ mamba env create -n rtd_env --file=read_the_docs_environment.yml
+# ======================================================================
+name: rtd_env
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python==3.12
+  - sphinx==7.2.6
+  - sphinx_rtd_theme==2.0.0
+  - sphinxcontrib-bibtex==2.6.2
+  - sphinx-autobuild==2021.3.14
+  - recommonmark==0.7.1
+  - docutils==0.20.1
+  - jinja2==3.1.3
+
+
diff --git a/docs/environment_files/read_the_docs_requirements.txt b/docs/environment_files/read_the_docs_requirements.txt
@@ -0,0 +1,18 @@
+# ======================================================================
+# ReadTheDocs requirements file
+#
+# If you wish to install the dependencies for building the ReadTheDocs
+# ReadTheDocs documentation from PyPI (the Python Package Index), use:
+#
+# $ pip install -r read_the_docs_requirements.txt
+# ======================================================================
+python==3.12
+sphinx==7.2.6
+sphinx_rtd_theme==2.0.0
+sphinxcontrib-bibtex==2.6.2
+sphinx-autobuild==2021.3.14
+recommonmark==0.7.1
+docutils==0.22.1
+jinja2==3.1.3
+
+
diff --git a/docs/environment_files/testing.yml b/docs/environment_files/testing.yml
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/environment.yml b/environment.yml
@@ -1 +1 @@
-docs/environment_files/environment.yml
+docs/environment_files/gcpy_environment.yml
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1 @@
+docs/environment_files/gcpy_requirements.txt
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		docs/environment_files/environment.yml
		docs/environment_files/gcpy_environment.yml