diff --git a/.github/workflows/build-gcpy-environment.yml b/.github/workflows/build-gcpy-environment.yml index e57f7359..0e1da74d 100644 --- 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 new file mode 100644 index 00000000..4bdc5879 --- /dev/null +++ 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 index 0941c287..b3efb372 100644 --- 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 index 25f0ae28..9b7515ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ 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) @@ -20,6 +22,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - 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 new file mode 100644 index 00000000..c98697fe --- /dev/null +++ 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 b/docs/environment_files/gcpy_environment.yml similarity index 74% rename from docs/environment_files/environment.yml rename to docs/environment_files/gcpy_environment.yml index 312999bc..fb33b0c8 100644 --- a/docs/environment_files/environment.yml +++ b/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 new file mode 100644 index 00000000..bcc9aff1 --- /dev/null +++ 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 new file mode 100644 index 00000000..8bd813b4 --- /dev/null +++ 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 new file mode 100644 index 00000000..8a5fe45a --- /dev/null +++ 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 deleted file mode 100644 index 3c6c9de0..00000000 --- a/docs/environment_files/testing.yml +++ /dev/null @@ -1,52 +0,0 @@ ---- -# ====================================================================== -# GCPy testing environment file. -# Intended to be used by the GCST for testing purposes. -# -# GCPy users should build the environment from "environment.yml", -# as this will specify package versions that are known to work. -# See: https://github.com/geoschem/gcpy/issues/284 -# ====================================================================== -name: testing -channels: - - conda-forge - - nodefaults -dependencies: - - awscli # Utilities for AWS cloud - - cartopy # Geospatial data processing - - cf_xarray # CF conventions for xarray - - dask # Parallel library; backend for xarray - - gridspec # Define Earth System Model grids - - ipython # Interactive Python (used by Jupyter) - - joblib # Parallelize python code - - jupyter # Jupyter Notebook - - matplotlib>=3.8 # Creates plots and visualizations - - netcdf4 # Python wrapper for netCDF - - netcdf-fortran # Python wrapper for netCDF-Fortran - - numpy # Optimized mathematical functions - - pandas # Tables/timeseries manipulation - - pip # Install packages from PyPi - - pylint # Python linter - - pyproj # Python map projections library - - python # Any python version prior to 3.10 - - pypdf # PDF utilities (bookmarks, etc.) - - recommonmark # Dependency for Sphinx - - requests # HTTP library - - scipy # Scientific python package - - sparselt # Regridding earth system model data - - tabulate # Pretty-printing for column data - - tk # Tcl/tk library - - xarray # Read data from netCDF etc files - # - # NOTE: These packages are known to work, so peg these versions - # - - 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/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 5e364b5f..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,16 +0,0 @@ -# Requirements for building the GCPy documentation -# -# NOTE: Use specific versions for Python packages instead of upper -# bounds. Using an upper bound will not necessarily install the -# intended version if there already is a version that meets the -# criteria present in the Python environment. -# -- Bob Yantosca and Lizzie Lundgren (27 Sep 2022) -# -# The following package versions have been proven to work together: -# -sphinx==3.5.4 -sphinx_rtd_theme==0.5.2 -sphinxcontrib-bibtex==2.2.0 -recommonmark -docutils==0.16 -jinja2==3.0.3 diff --git a/environment.yml b/environment.yml index bea0bd1b..f9a29767 120000 --- a/environment.yml +++ b/environment.yml @@ -1 +1 @@ -docs/environment_files/environment.yml \ No newline at end of file +docs/environment_files/gcpy_environment.yml \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 120000 index 00000000..a1ba061b --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +docs/environment_files/gcpy_requirements.txt \ No newline at end of file