Document PR #707 dependency changes: Python >=3.11, fregrid unbundled

[Copilot]

Describe your changes

Minimal documentation updates for PR #707 dependency changes. Updates outdated information and adds optional setup instructions for fre-nctools across all documentation files.

Changes Made

• fre/app/regrid_xy/README.md: Updated line 5 to reflect:

  • Python version requirement changed from 3.9.16 to >= 3.11 (tested/developed with Python 3.12)
  • fre-nctools no longer bundled as package dependency; must be loaded externally via module load fre-nctools
  • Fixed module reference from metomi to xarray to match actual dependencies

• README.md: Added optional fre-nctools loading instructions to setup sections:

  • Module loading via lmod (line 45-46)
  • Conda environment activation for GFDL systems (line 55-56)
  • Conda environment activation for Gaea systems (line 62-63)
  • Conda install instructions (line 76-77)

• CONTRIBUTING.md: Added optional step for developers to load fre-nctools for regridding and time-averaging routines (line 6)

• docs/setup.rst: Added optional fre-nctools loading instruction after pip install -e . in the development setup section

• docs/contributing_to_doc.rst: Added optional fre-nctools loading instruction after conda activate fre-cli in the full environment approach section

All changes are surgical edits to existing documentation, avoiding addition of new sections or files. Instructions for fre-nctools are presented as optional commented steps to guide users without being intrusive.

Issue ticket number and link (if applicable)

Related to PR #707 dependency changes

Checklist before requesting a review

• I ran my code
• I tried to make my code readable
• I tried to comment my code
• I wrote a new test, if applicable
• I wrote new instructions/documentation, if applicable
• I ran pytest and inspected it's output
• I ran pylint and attempted to implement some of it's feedback
• No print statements; all user-facing info uses logging module

Original prompt

Overview

PR #707 introduces significant dependency changes that require documentation updates. This PR adds comprehensive documentation to reflect these changes.

Changes Made in PR #707

1. Python version requirement changed from 3.11.* to >=3.11
2. CMOR version requirement changed from >=3.11.* to >=3.14
3. fre-nctools removed as a package dependency
4. Tests now check for fregrid using shutil.which() and skip if not available
5. Build requirements added: python, pip, setuptools, wheel

Documentation Updates Needed

1. Update README.md

Add a new "Requirements" section after the "Intro" section and before "Quickstart" to document:

• Python version requirement: >= 3.11 (currently tested on Python 3.12)
• CMOR version requirement: >= 3.14
• Note about fre-nctools no longer being a package dependency

The new section should be added around line 30, formatted as:

## **Requirements**

`fre-cli` requires:
- **Python** >= 3.11 (currently tested and developed on Python 3.12)
- **CMOR** >= 3.14 (upgraded from 3.11 for latest PCMDI/cmor features)

### Optional External Dependencies

Some `fre` subtools require external dependencies that are **not** included in the conda package:

- **fregrid** (from fre-nctools): Required for `fre app regrid_xy` operations
  - Must be loaded separately via module system or installed independently
  - Tests for regrid_xy functionality will be automatically skipped if not available

**On GFDL/Gaea systems:**
```bash
module load fre-nctools

Or install separately:

conda install -c noaa-gfdl fre-nctools

### 2. Update CONTRIBUTING.md
Add a new section after line 7 (after the "For Developers" introduction) documenting the development environment setup:

```markdown
### **Development Environment Setup**

#### Python Version Support
`fre-cli` supports Python >= 3.11. The package is currently tested and developed on Python 3.12. When setting up your development environment, ensure you use a compatible Python version.

#### External Dependencies
Some functionality requires external tools not included in the conda package dependencies:

- **fregrid** (from fre-nctools): Required for `fre app regrid_xy` operations
  - Must be loaded separately via module or environment
  - Tests for this functionality will be automatically skipped if `fregrid` is not in your PATH
  - Use `which fregrid` to check availability

**Testing with Optional Dependencies:**
When running tests, you may see some tests skipped with messages like:

SKIPPED [1] fre/app/regrid_xy/tests/test_regrid_xy.py:85: fregrid not in env. it was removed from package reqs. you must load it externally

This is expected behavior when optional dependencies are not available. To run all tests:
```bash
# On GFDL/Gaea systems
module load fre-nctools
pytest

Key Dependency Versions

• CMOR >= 3.14 (latest PCMDI/cmor features)
• numpy == 1.26.4 (pinned for stability)
• netcdf4 >= 1.7.*

### 3. Update fre/app/regrid_xy/README.md
Update the existing regrid_xy README to reflect that fregrid is no longer bundled. Update line 5 which currently states:

Current:

requires fre-nctools and fregrid to be in one's PATH variable, and python3 (tested/developed with python 3.9.16). there should be netCDF4 and metomi python modules in one's python environment for imports. pytest and nccmp is required for tests. pylint recommended for future developers working on this tool.

Replace with:
```markdown
## Prerequisites

**Important:** As of fre-cli version 2025.04+, `fregrid` from `fre-nctools` is **no longer bundled** as a package dependency and must be available in your environment separately.

### Required in PATH
- **fregrid** - Must be loaded externally from fre-nctools
  
  To check if fregrid is available:
  ```bash
  which fregrid

If not available, on GFDL/Gaea systems:

module load fre-nctools

Or install separately:

conda install -c noaa-gfdl fre-nctools

Python Requirements

• Python >= 3.11 (tested/developed with Python 3.12)
• netCDF4 python module
• xarray python module
• pytest and nccmp for running tests
• pylint recommended for developers

Note: Without fregrid in your PATH, regrid_xy operations will fail, and related tests will be automatically skipped.

### 4. Create a new file: docs/DEPENDENCIES.md
Create a comprehensive dependency reference document at `docs/DEPENDENCIES.md`:

```markdown
# fre-cli Dependencies Reference

This document describes the dependencies required for `fre-cli` and provides guidance on version requirements and optional dependencies.

## Core Dependencies

### Python
- **Requirement:** >= 3.11
- **Tested versions:** 3.11, 3.12
- **Notes:** As of the 2025.04 release cycle, Python 3.11 and 3.12 are officially supported

### CMOR (Climate Model Output Rewriter)
- **Requirement:** >= 3.14
- **Channel:** conda-forge
- **Notes:** U...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

[ilaflott]

@copilot too wordy, very much overkill. do these steps in order-

• first, revert all your changes, we will start from step 1.
• second, read all documentation in the repository and note anything that may be affected by the changes in PR tweak env/reqs to utilize latest version(s) of PCMDI/cmor #707
• third, go over each thing you noted down in the previous step and minimally edit the documentation.

do not add new sections nor files unless absolutely necessary. favor adjusting the current language in the doc instead of adding completely new language.

[Copilot]

@copilot too wordy, very much overkill. do these steps in order-

• first, revert all your changes, we will start from step 1.
• second, read all documentation in the repository and note anything th...

Reverted all changes and made minimal surgical edit. Only updated fre/app/regrid_xy/README.md line 5:

• Python 3.9.16 → Python >=3.11 (tested/developed with 3.12)
• Noted fre-nctools no longer bundled, must load externally
• Fixed metomi → xarray

Commit: efe3b6d

[ilaflott]

@copilot ok now find specific sections with set-up instructions, and add a step with a comment in the direction of, "# optional, load fre-nctools into your PATH to gain access to regridding and certain time-averaging routines.". Keep being surgical and minimal with edits

[Copilot]

@copilot ok now find specific sections with set-up instructions, and add a step with a comment in the direction of, "# optional, load fre-nctools into your PATH to gain access to regridding and certai...

Added optional fre-nctools loading instructions to all setup sections:

• README.md: 3 locations (lmod, GFDL conda, Gaea conda, and conda install)
• CONTRIBUTING.md: 1 location (developer setup)

Each includes commented instruction about loading fre-nctools for regridding/time-averaging routines.

Commit: cb96f5c

[ilaflott]

@copilot now do what you just did, but dig into the files under docs/

[Copilot]

@copilot now do what you just did, but dig into the files under docs/

Added optional fre-nctools loading instructions to docs/ setup sections:

• docs/setup.rst: After pip install -e . in development setup
• docs/contributing_to_doc.rst: After conda activate in full environment approach

Each includes commented instruction about loading fre-nctools for regridding/time-averaging routines.

Commit: 55aec31