diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 281d94a..469d4b1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,7 +22,7 @@ jobs: with: python-version: "3.12" cache: pip - cache-dependency-path: doc/requirements.txt + cache-dependency-path: pyproject.toml - name: Install Pandoc run: | @@ -32,8 +32,8 @@ jobs: - name: Install documentation dependencies run: | python -m pip install --upgrade pip - python -m pip install -r doc/requirements.txt + python -m pip install -e ".[docs]" - name: Build documentation run: | - python -m sphinx -W -b html doc/source doc/build/html + python -m sphinx -E -W --keep-going -b html doc/source doc/build/html diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9c6a7d4..b3163eb 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -24,5 +24,9 @@ formats: # Python requirements for building documentation python: install: - # Install additional requirements for building docs - - requirements: doc/requirements.txt + # Install the package and the documentation dependencies declared in + # pyproject.toml. + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.md b/README.md index 090fa73..abd1620 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,38 @@ [![Documentation Status](https://readthedocs.org/projects/pyfvcom2/badge/?version=latest)](https://pyfvcom2.readthedocs.io/en/latest/?badge=latest) -A Python package for processing FVCOM (Finite Volume Community Ocean Model) data. +A Python package for processing FVCOM (Finite Volume Community Ocean Model) +data. ## Description -PyFVCOM2 is a Python library designed to work with FVCOM model output data, providing tools for data analysis, visualization, and processing of unstructured grid ocean model results. It is intended to be the successor of PyFVCOM. +PyFVCOM2 is a Python library for working with FVCOM model data, including +reading meshes and outputs, preparing forcing files, interpolating +oceanographic data, analysing tides, and processing unstructured-grid model +results. It is the successor to PyFVCOM. ## Installation -```bash -# Clone the repository -git clone -cd pyfvcom2 - -# Create a virtual environment -python -m venv venv -source venv/bin/activate # On Windows: venv\Scripts\activate - -# Install in development mode -pip install -e . -``` +Installation instructions are available in the +[documentation](https://pyfvcom2.readthedocs.io/en/latest/installation.html). ## Usage -```python -import pyfvcom2 - -# Your code here -``` +For first steps, see the +[hosted documentation](https://pyfvcom2.readthedocs.io/en/latest/). +Worked examples are available in the +[Cookbook](https://pyfvcom2.readthedocs.io/en/latest/cookbook/index.html). ## Development -This project follows Python best practices: +Development setup and source installation instructions are available in the +[installation documentation](https://pyfvcom2.readthedocs.io/en/latest/installation.html). + +The generated API reference is available in the +[API documentation](https://pyfvcom2.readthedocs.io/en/latest/api.html). -- Python 3.8+ compatibility -- PEP 8 style guidelines -- Type hints where appropriate -- Comprehensive docstrings -- Unit testing with pytest +Please report bugs and request features through the +[issue tracker](https://github.com/pmlmodelling/pyfvcom2/issues). ## License @@ -47,11 +41,11 @@ This project is licensed under the MIT License - see the [LICENSE.txt](https://g ## Contributing -The team welcome contributions to the project! These include: +The team welcomes contributions to the project. These include: -- Reviewling pull requests. +- Reviewing pull requests. - Creating, commenting on and resolving issues. - Preparing documentation. - [Financial donations](https://pml.ac.uk/support-us/#how) to help support the work of the core team. -If you are planning a large change to the code, please contact the team to discuss this first. +If you are planning a large change to the code, please open an issue first so it can be discussed. diff --git a/doc/source/acknowledgements.rst b/doc/source/acknowledgements.rst index aedca57..c7510ed 100644 --- a/doc/source/acknowledgements.rst +++ b/doc/source/acknowledgements.rst @@ -1,14 +1,10 @@ Acknowledgements ================ -Funding -------- - -Funding acknowledgements will be added as they are confirmed. - Contributors ------------ +PyFVCOM2 builds on the work of the original PyFVCOM authors and contributors. See the project repository for the current contributor history. Dependencies diff --git a/doc/source/conf.py b/doc/source/conf.py index 1b14188..e2ac487 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,19 +17,11 @@ # import os import sys -import types sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../../pyfvcom2')) -if 'pyfvcom2.version' not in sys.modules: - version_module = types.ModuleType('pyfvcom2.version') - version_module.short_version = 'X.Y.Z' - version_module.version = 'X.Y.Z' - version_module.full_version = 'X.Y.Z' - sys.modules['pyfvcom2.version'] = version_module - # -- General configuration ------------------------------------------------ @@ -47,7 +39,6 @@ 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.mathjax', - 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx_copybutton', 'nbsphinx', @@ -116,17 +107,14 @@ # |version| and |release|, also used in various other places throughout the # built documents. # -# Import version from the package -try: - from pyfvcom2.version import short_version, version as full_version - # The short X.Y version. - version = short_version - # The full version, including alpha/beta/rc tags. - release = full_version -except ImportError: - # Fallback if import fails - version = 'X.Y.Z' - release = 'X.Y.Z' +# Import version from the package. Let the documentation build fail if the +# package version cannot be resolved, so published docs do not show a fallback. +from pyfvcom2.version import short_version, version as full_version + +# The short X.Y version. +version = short_version +# The full version, including alpha/beta/rc tags. +release = full_version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -146,6 +134,31 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False + +def remove_unpublished_notes_from_autodoc(app, what, name, obj, options, lines): + """Keep source working notes out of the published API documentation.""" + unpublished_note_prefixes = tuple( + prefix.upper() for prefix in ('todo', 'tbd', 'fixme') + ) + filtered_lines = [] + skip_continuation = False + + for line in lines: + stripped = line.lstrip() + if stripped.startswith(unpublished_note_prefixes): + skip_continuation = True + continue + if skip_continuation and stripped: + continue + skip_continuation = False + filtered_lines.append(line) + + lines[:] = filtered_lines + + +def setup(app): + app.connect('autodoc-process-docstring', remove_unpublished_notes_from_autodoc) + # Google analytics googleanalytics_id = 'G-5045ZREHMB' diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 3dd0070..d43afdd 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -4,16 +4,17 @@ Contributing ************ -We welcome contributions to PyFVCOM2! This guide will help you get started with contributing code, documentation, or bug reports. +We welcome contributions to PyFVCOM2. This guide covers the development setup, +checks, and review process for code, documentation, and bug reports. Development Setup ================= -1. **Fork the repository** on GitHub +1. **Fork the repository** on GitHub if you plan to open a pull request. -2. **Clone your fork**:: +2. **Clone your fork or the upstream repository**:: - git clone https://github.com/yourusername/pyfvcom2.git + git clone https://github.com/pmlmodelling/pyfvcom2.git cd pyfvcom2 3. **Create a development environment**:: @@ -21,11 +22,7 @@ Development Setup conda env create -f environment.yml conda activate pyfvcom2 -4. **Install in development mode**:: - - pip install -e . - -5. **Install development dependencies**:: +4. **Install the package with development dependencies**:: pip install -e ".[dev]" @@ -39,13 +36,16 @@ Code Standards - Write docstrings in NumPy/SciPy format - Keep line length under 88 characters (Black formatter default) -**Code Quality:** +**Required checks:** - Run tests: ``pytest tests/`` -- Check formatting: ``black --check pyfvcom2/`` -- Check imports: ``isort --check-only pyfvcom2/`` -- Type checking: ``mypy pyfvcom2/`` -- Linting: ``flake8 pyfvcom2/`` +- Check for Python syntax and undefined-name errors: + ``flake8 pyfvcom2 --jobs=1 --count --select=E9,F63,F7,F82 --show-source --statistics`` + +**Optional local checks:** + +- Run broader linting: + ``flake8 pyfvcom2 --jobs=1 --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics`` **Testing:** @@ -67,9 +67,10 @@ Submitting Changes 4. **Update documentation** if needed -5. **Run the test suite**:: +5. **Run the required checks**:: pytest tests/ + flake8 pyfvcom2 --jobs=1 --count --select=E9,F63,F7,F82 --show-source --statistics 6. **Commit your changes**:: @@ -88,14 +89,12 @@ Pull Request Guidelines **Before submitting:** - Ensure all tests pass -- Update CHANGELOG.rst with your changes -- Add yourself to AUTHORS.rst (if not already there) - Write a clear PR description explaining the changes **PR Review Process:** - All PRs must be reviewed by at least one maintainer -- Automated checks (CI/CD) must pass +- Automated checks must pass - Documentation must be updated for API changes - Breaking changes require discussion and approval @@ -114,14 +113,13 @@ Types of Contributions - API documentation improvements - Tutorial and example development - User guide enhancements -- Translation efforts **Other Contributions:** - Bug reports with reproducible examples - Feature requests with use cases - Performance benchmarking -- Community support and discussions +- Answering questions in issues and pull requests Reporting Issues ================ @@ -147,18 +145,15 @@ Communication ============= - **GitHub Issues**: Bug reports and feature requests -- **GitHub Discussions**: General questions and ideas - **Pull Requests**: Code review and technical discussion -- **Email**: Contact maintainers for sensitive issues Recognition =========== Contributors are recognized in: -- AUTHORS.rst file -- Release notes and changelog - GitHub contributor statistics -- Conference presentations (with permission) +- Pull request and issue history +- Release notes when relevant -Thank you for contributing to PyFVCOM2! \ No newline at end of file +Thank you for contributing to PyFVCOM2! diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 0000000..4576e1d --- /dev/null +++ b/doc/source/getting_started.rst @@ -0,0 +1,26 @@ +.. _getting_started: + +Getting Started +=============== + +After installing PyFVCOM2, check that the package imports correctly: + +.. code-block:: python + + import pyfvcom2 + +Most workflows start by reading a mesh, loading model or forcing data, and then +using one of the higher-level managers or interpolators to prepare FVCOM inputs +or analyse outputs. + +For worked examples, start with the :doc:`cookbook/index`. The cookbook covers +common tasks such as: + +* comparing TPXO tidal harmonics; +* creating tide-only FVCOM inputs; +* interpolating FVCOM and CMEMS data; +* generating restart and nesting files; +* applying forcing ramps; and +* smoothing bathymetry. + +For details on individual functions and classes, see the :doc:`api`. diff --git a/doc/source/index.rst b/doc/source/index.rst index 443c943..404880b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,14 +1,36 @@ -.. include:: ../../README.md - :parser: myst_parser.sphinx_ +PyFVCOM2 +======== + +PyFVCOM2 is a Python package for working with FVCOM (Finite Volume Community +Ocean Model) data. It provides tools for reading FVCOM meshes and outputs, +building forcing files, interpolating oceanographic data, analysing tides, and +preparing common FVCOM inputs. + +PyFVCOM2 is the successor to PyFVCOM. It keeps the focus on practical FVCOM +pre- and post-processing while modernising the package structure and +documentation. + +Where to Start +-------------- + +* :doc:`installation` + Install PyFVCOM2 and its scientific Python dependencies. +* :doc:`getting_started` + Learn the basic workflow and find the first examples to run. +* :doc:`api` + Browse the generated API reference for modules, classes, and functions. +* :doc:`cookbook/index` + Follow worked examples for tides, interpolation, restart files, nesting, and + bathymetry smoothing. .. toctree:: :maxdepth: 1 :caption: Contents installation + getting_started cookbook/index api contributing license acknowledgements - diff --git a/doc/source/installation.rst b/doc/source/installation.rst index d3b6c9a..9a58a74 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,80 +1,111 @@ .. _installation: -************ Installation -************ +============ -PyFVCOM2 can be installed using pip or conda. We recommend using conda for scientific Python environments as it handles complex dependencies more reliably. +PyFVCOM2 is currently installed from source. Package-index installation is not +available yet, so commands such as ``pip install pyfvcom2`` or +``conda install -c conda-forge pyfvcom2`` are not documented as supported +installation methods. -Using Conda (Recommended) -========================= +Python Versions +--------------- -Create a new conda environment with PyFVCOM2:: +The project metadata requires Python 3.8 or newer. The package classifiers +currently advertise Python 3.9, 3.10, and 3.11. - conda env create -f environment.yml - conda activate pyfvcom2 +Normal User Installation +------------------------ -Or install into an existing environment:: +Use this route if you want to install PyFVCOM2 from a local checkout without +installing development tools. - conda install -c conda-forge pyfvcom2 +First, create and activate an environment: -Using Pip -========= +.. code-block:: bash -Install from PyPI:: + conda create -n pyfvcom2 -c conda-forge python=3.11 pip + conda activate pyfvcom2 - pip install pyfvcom2 +Then clone and install the package: -For development installation:: +.. code-block:: bash - git clone https://github.com/pmlmodelling/pyfvcom2.git - cd pyfvcom2 - pip install -e . + git clone https://github.com/pmlmodelling/pyfvcom2.git + cd pyfvcom2 + python -m pip install . -Dependencies -============ +Development Installation +------------------------ -PyFVCOM2 requires the following packages: +Use this route if you want to edit the source code, run tests, or build the +documentation. -**Core Dependencies:** +.. code-block:: bash -- Python >= 3.8 -- NumPy >= 1.19 -- SciPy >= 1.5 -- NetCDF4 >= 1.5 -- xarray >= 0.16 + git clone https://github.com/pmlmodelling/pyfvcom2.git + cd pyfvcom2 + conda env create -f environment.yml + conda activate pyfvcom2 -**Visualization Dependencies:** +The development environment installs PyFVCOM2 in editable mode through the +``environment.yml`` file. -- Matplotlib >= 3.3 -- Cartopy >= 0.18 +To install the editable package manually in an existing environment: -**Optional Dependencies:** +.. code-block:: bash -- Jupyter (for notebook examples) + python -m pip install -e . -Verifying Installation -====================== +Installation Test +----------------- -Test your installation:: +Check that PyFVCOM2 imports: - python -c "import pyfvcom2; print(pyfvcom2.__version__)" +.. code-block:: bash -Run the test suite:: + python -c "import pyfvcom2" - python -m pytest tests/ +To print the installed version: -Troubleshooting -=============== +.. code-block:: bash + + python -c "import pyfvcom2; print(pyfvcom2.__version__)" + +Dependencies +------------ + +Runtime dependencies are defined in ``pyproject.toml``. They currently include: + +* ``numpy>=1.19.0`` +* ``scipy>=1.5.0`` +* ``matplotlib>=3.3.0`` +* ``netCDF4>=1.5.0`` +* ``xarray>=0.16.0`` +* ``pyproj`` +* ``cftime>=1.6.0`` +* ``cartopy>=0.20.0`` +* ``cmocean>=2.0`` +* ``stripy>=0.6.0`` +* ``utide`` -**Common Issues:** +For scientific Python environments, conda-forge is recommended for compiled +geospatial and NetCDF dependencies such as ``cartopy``, ``pyproj``, and +``netCDF4``. -1. **Cartopy installation problems**: Install via conda-forge channel -2. **NetCDF4 library not found**: Install libnetcdf development headers -3. **GEOS/PROJ errors**: Update to latest cartopy version +Optional Development and Documentation Dependencies +--------------------------------------------------- -**Getting Help:** +Development dependencies, including ``pytest``, ``black``, ``flake8``, ``mypy``, +and ``pre-commit``, are listed in the ``dev`` optional dependency group in +``pyproject.toml``. + +Documentation dependencies are listed in the ``docs`` optional dependency group +and in ``doc/requirements.txt``. + +Troubleshooting +--------------- -- Check the GitHub Issues page -- Join the PyFVCOM2 discussions -- Contact the development team \ No newline at end of file +If installation fails while building compiled dependencies, create the +environment with conda-forge first, then install PyFVCOM2 into that environment. +This avoids many local compiler and system-library issues. diff --git a/doc/source/license.rst b/doc/source/license.rst index 1fcef14..ad37d61 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -9,27 +9,14 @@ PyFVCOM2 is distributed under the MIT License. .. literalinclude:: ../../LICENSE.txt :language: text -Third-Party Licenses -==================== +Third-Party Dependencies +======================== -PyFVCOM2 depends on several third-party packages, each with their own licenses: - -**Core Dependencies:** - -- **NumPy**: BSD-3-Clause License -- **SciPy**: BSD-3-Clause License -- **NetCDF4**: MIT License -- **xarray**: Apache License 2.0 -- **Matplotlib**: PSF-based License -- **Cartopy**: LGPL-3.0 License - -**Development Dependencies:** - -- **pytest**: MIT License -- **Black**: MIT License -- **isort**: MIT License -- **mypy**: MIT License -- **Sphinx**: BSD-2-Clause License +PyFVCOM2 uses third-party packages from the Python scientific computing and +geospatial ecosystem. Runtime, development, and documentation dependencies are +listed in ``pyproject.toml``, ``environment.yml``, and +``doc/requirements.txt``. Those dependencies are distributed under their own +license terms. Copyright Notice ================ @@ -60,4 +47,4 @@ Contributor Agreement By contributing to PyFVCOM2, you agree that your contributions will be licensed under the same MIT License that covers the project. You retain copyright to your contributions while granting Plymouth Marine Laboratory and the PyFVCOM2 project -the right to distribute your contributions under this license. \ No newline at end of file +the right to distribute your contributions under this license. diff --git a/pyproject.toml b/pyproject.toml index e8e1b6b..b087ba5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,9 +67,9 @@ docs = [ ] [project.urls] -Homepage = "https://github.com/yourusername/pyfvcom2" -Repository = "https://github.com/yourusername/pyfvcom2.git" -Issues = "https://github.com/yourusername/pyfvcom2/issues" +Homepage = "https://github.com/pmlmodelling/pyfvcom2" +Repository = "https://github.com/pmlmodelling/pyfvcom2.git" +Issues = "https://github.com/pmlmodelling/pyfvcom2/issues" "Original PyFVCOM" = "https://github.com/pmlmodelling/PyFVCOM" [tool.setuptools.dynamic]