Skip to content

Improve Cartopy CLI and add shared tutorial environment setup - #2

Open
enikidis wants to merge 3 commits into
mainfrom
dev
Open

Improve Cartopy CLI and add shared tutorial environment setup#2
enikidis wants to merge 3 commits into
mainfrom
dev

Conversation

@enikidis

Copy link
Copy Markdown
Collaborator

Summary

This PR makes the tutorial repository easier to run and publish by improving the Cartopy command-line tutorial and adding shared environment setup for the NetCDF and Cartopy tutorials.

Changes

  • Refactor Cartopy/cera_cartopy.py into a clearer command-line workflow.
  • Add CSV input validation for required columns: station_id, lat, and lon.
  • Add Cartopy CLI options for:
    • --output
    • --no-show
    • --title
  • Update Cartopy documentation with the expected CSV format and script examples.
  • Add a shared Conda environment file: environment.yml.
  • Add a pip fallback file: requirements.txt.
  • Update the root README with setup and run instructions.
  • Update the NetCDF and Cartopy tutorial READMEs to use the shared environment.
  • Replace active notebook pip install cells with non-mutating setup guidance.
  • Standardize notebooks on the Python (cera-tutorials) kernel.
  • Add notebook-only checks to avoid re-downloading existing tutorial data files.
  • Update .gitignore for generated files, local environments, downloaded sample data, and output images.

Testing

  • Ran python3 -m py_compile Cartopy/cera_cartopy.py.
  • Ran python3 -m py_compile Analyzing_NetCDF/NetCDF_Tutorial/net_CDF4.py.
  • Validated both notebooks with jq empty.
  • Verified no active notebook pip install commands remain.
  • Ran git diff --check.
  • Verified Cartopy runtime imports in the cera-tutorials Conda environment.
  • Smoke-tested the Cartopy CLI commands:
    • python3 cera_cartopy.py water_level_stations.csv
    • python3 cera_cartopy.py water_level_stations.csv --output station_map.png
    • python3 cera_cartopy.py water_level_stations.csv --output station_map.png --no-show
    • python3 cera_cartopy.py water_level_stations.csv --title "Water level stations"

Notes

Downloaded tutorial data files remain local and ignored by git:

  • Cartopy/water_level_stations.csv
  • Analyzing_NetCDF/NetCDF_Tutorial/maxele.63.nc

Add shared environment files and update the tutorial documentation so users can
clone the repository, create one environment, and run both the NetCDF and
Cartopy tutorials without ad hoc package installation.
Add repository-level dependency files:
- Add environment.yml for the recommended Conda/Mamba workflow.
- Use the cera-tutorials environment name.
- Use conda-forge for geospatial/scientific dependencies.
- Include Python 3.12, NumPy, pandas, Matplotlib, netCDF4, Cartopy,
Pillow, ipywidgets, JupyterLab, notebook, and ipykernel.
- Add requirements.txt as a pip fallback with the equivalent Python packages.
Update documentation:
- Add root README setup instructions for Conda/Mamba and pip fallback.
- Add root README run commands for the NetCDF and Cartopy tutorials.
- Update Cartopy README to point users at the shared root environment.
- Update Analyzing_NetCDF README with local run instructions.
- Fix stale NetCDF tutorial links to point at files in this repository.
- Fix the "Jupiter Notebook" typo to "Jupyter Notebook".
Clean up notebook environment handling:
- Replace executable pip install cells in both notebooks with non-mutating
setup guidance.
- Document the shared cera-tutorials kernel inside the notebooks.
- Keep pip fallback commands as commented examples only.
- Standardize both notebooks on the Python (cera-tutorials) kernel.
- Avoid automatic package installation when users run all notebook cells.
Improve tutorial data handling:
- Keep README download commands simple for copy/paste terminal usage.
- Add notebook-only checks before downloading tutorial data files.
- Skip re-downloading water_level_stations.csv in the Cartopy notebook when it
already exists.
- Skip re-downloading maxele.63.nc in the NetCDF notebook when it already
exists.
Update ignore rules:
- Ignore Python cache files and notebook checkpoints.
- Ignore local virtual environments and .env files.
- Ignore Cartopy generated map images.
- Ignore NetCDF tutorial output text files.
- Ignore downloaded NetCDF sample files, including repeated wget suffixes.
Validation:
- Verified both notebooks are valid JSON with jq.
- Verified no active notebook pip install commands remain.
- Ran git diff --check successfully.
- Ran py_compile successfully for the Cartopy and NetCDF Python scripts.
@enikidisenikidis self-assigned this Jun 12, 2026
@enikidisenikidis added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 12, 2026
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@enikidis