pycequeau 0.0.2__tar.gz

pycequeau-0.0.2/DEVELOPMENT.rst

@@ -0,0 +1,318 @@
+Development Guide
+=================
+
+This guide provides instructions for developers working on the pycequeau package, including setup, testing, and publishing to PyPI.
+
+Development Setup
+-----------------
+
+1. Clone the repository:
+
+.. code-block:: bash
+
+    git clone https://github.com/erinconv/pycequeau.git
+    cd pycequeau
+
+2. Create a conda environment (recommended for geospatial dependencies):
+
+.. code-block:: bash
+
+    conda env create -f environment.yml
+    conda activate pycequeau
+
+3. Install the package in development mode:
+
+.. code-block:: bash
+
+    pip install -e .
+
+4. Install development dependencies:
+
+.. code-block:: bash
+
+    pip install -e .[dev]
+
+Building the Package
+--------------------
+
+1. Install build tools:
+
+.. code-block:: bash
+
+    pip install build twine
+
+2. Clean previous builds:
+
+.. code-block:: bash
+
+    # Windows PowerShell
+    Remove-Item -Recurse -Force dist/, build/, *.egg-info/ -ErrorAction SilentlyContinue
+
+    # Linux/Mac
+    rm -rf dist/ build/ *.egg-info/
+
+3. Build the package:
+
+.. code-block:: bash
+
+    python -m build
+
+This creates:
+- ``dist/pycequeau-X.X.X.tar.gz`` (source distribution)
+- ``dist/pycequeau-X.X.X-py3-none-any.whl`` (wheel distribution)
+
+Testing the Package
+-------------------
+
+1. Test local installation:
+
+.. code-block:: bash
+
+    pip install dist/pycequeau-*.whl --force-reinstall
+
+2. Test package import:
+
+.. code-block:: python
+
+    import pycequeau
+    print(f"Version: {pycequeau.__version__}")
+    print(f"Available modules: {pycequeau.__all__}")
+
+3. Test all modules:
+
+.. code-block:: python
+
+    import pycequeau.core
+    import pycequeau.meteo
+    import pycequeau.physiographic
+    import pycequeau.simulations
+    print("All modules imported successfully!")
+
+Publishing to PyPI
+------------------
+
+### Prerequisites
+
+1. Create PyPI accounts:
+   - Production: `https://pypi.org/`
+   - Test: `https://test.pypi.org/`
+
+2. Create API tokens:
+   - Go to account settings → API tokens
+   - Create tokens for both production and test PyPI
+   - Save the tokens securely
+
+3. Configure credentials in ``~/.pypirc``:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers = pypi testpypi
+
+    [pypi]
+    username = __token__
+    password = pypi-YOUR_ACTUAL_TOKEN_HERE
+
+    [testpypi]
+    repository = https://test.pypi.org/legacy/
+    username = __token__
+    password = pypi-YOUR_TEST_TOKEN_HERE
+
+### Publishing Steps
+
+1. **Test Upload (Recommended)**:
+
+.. code-block:: bash
+
+    # Upload to test PyPI first
+    twine upload --repository testpypi dist/*
+
+    # Test installation from test PyPI
+    pip install --index-url https://test.pypi.org/simple/ pycequeau
+
+2. **Production Upload**:
+
+.. code-block:: bash
+
+    # Upload to production PyPI
+    twine upload dist/*
+
+3. **Verify Installation**:
+
+.. code-block:: bash
+
+    # Test installation from PyPI
+    pip install pycequeau
+
+    # Test with optional dependencies
+    pip install pycequeau[geo]
+    pip install pycequeau[all]
+
+### Version Management
+
+1. Update version in ``pyproject.toml``:
+
+.. code-block:: toml
+
+    version = "0.0.2"  # or 0.1.0, 1.0.0, etc.
+
+2. Follow semantic versioning:
+   - ``MAJOR.MINOR.PATCH``
+   - Examples: ``0.0.1``, ``0.1.0``, ``1.0.0``
+   - PyPI doesn't allow re-uploading the same version
+
+3. Rebuild and upload:
+
+.. code-block:: bash
+
+    python -m build
+    twine upload dist/*
+
+Package Structure
+-----------------
+
+The package follows this structure:
+
+.. code-block:: text
+
+    pycequeau/
+    ├── src/
+    │   └── pycequeau/
+    │       ├── __init__.py
+    │       ├── core/
+    │       ├── meteo/
+    │       ├── physiographic/
+    │       └── simulations/
+    ├── docs/
+    ├── matlab/
+    ├── pyproject.toml
+    ├── requirements.txt
+    ├── environment.yml
+    ├── MANIFEST.in
+    └── README.rst
+
+Dependencies
+------------
+
+### Required Dependencies
+- ``pyproj``: Coordinate transformations
+- ``xarray``: N-dimensional arrays
+- ``scipy``: Scientific computing
+- ``matplotlib``: Plotting
+- ``shapely``: Geometric objects
+
+### Optional Dependencies
+
+**Geospatial (``[geo]``)**:
+- ``gdal``: Geospatial data processing
+- ``geopandas``: Geospatial data analysis
+- ``rasterstats``: Raster statistics
+- ``netcdf4``: NetCDF file handling
+
+**Development (``[dev]``)**:
+- ``pytest``: Testing framework
+- ``autopep8``: Code formatting
+- ``ipykernel``: Jupyter notebook support
+
+**All (``[all]``)**:
+- Includes all geospatial and development dependencies
+
+Installation Commands
+--------------------
+
+.. code-block:: bash
+
+    # Basic installation
+    pip install pycequeau
+
+    # With geospatial functionality
+    pip install pycequeau[geo]
+
+    # With development tools
+    pip install pycequeau[dev]
+
+    # Everything
+    pip install pycequeau[all]
+
+    # From source
+    git clone https://github.com/erinconv/pycequeau.git
+    cd pycequeau
+    pip install .
+
+Troubleshooting
+---------------
+
+### Common Issues
+
+1. **HDF5 headers not found**:
+   - This occurs when installing geospatial dependencies
+   - Use conda environment: ``conda env create -f environment.yml``
+   - Or install pre-built packages: ``conda install gdal geopandas netcdf4``
+
+2. **GDAL installation issues**:
+   - GDAL requires system libraries
+   - Use conda for easier installation
+   - Or install GDAL system package first
+
+3. **Build failures**:
+   - Ensure all dependencies are installed
+   - Check Python version compatibility (3.8+)
+   - Clean build artifacts before rebuilding
+
+### Testing Installation
+
+.. code-block:: bash
+
+    # Test basic functionality
+    python -c "import pycequeau; print('Success!')"
+
+    # Test geospatial functionality
+    python -c "import pycequeau; import geopandas; print('Geo features work!')"
+
+    # Test all modules
+    python -c "from pycequeau import core, meteo, physiographic, simulations; print('All modules work!')"
+
+Contributing
+------------
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test your changes:
+
+.. code-block:: bash
+
+    python -m build
+    pip install dist/pycequeau-*.whl --force-reinstall
+
+5. Submit a pull request
+
+### Code Style
+
+- Follow PEP 8 guidelines
+- Use ``autopep8`` for formatting
+- Add docstrings to functions and classes
+- Include type hints where appropriate
+
+### Testing
+
+- Add tests for new functionality
+- Ensure all tests pass before submitting
+- Test installation in clean environment
+
+After Publishing
+----------------
+
+Once published, your package will be available at:
+- PyPI: `https://pypi.org/project/pycequeau/`
+- Installation: ``pip install pycequeau``
+
+Consider setting up:
+- Documentation on Read the Docs
+- Continuous integration with GitHub Actions
+- Automated testing and publishing workflows
+
+
+
+# Upload to production PyPI
+twine upload dist/*