42 docs fill out

.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

.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

README.md

@@ -2,56 +2,50 @@
 
 [![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 <repository-url>
-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
 
 This project is licensed under the MIT License - see the [LICENSE.txt](https://github.com/pmlmodelling/pyfvcom2/blob/main/LICENSE.txt) file for details.
 
 ## 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.

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

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'
 

doc/source/contributing.rst

@@ -4,28 +4,25 @@
 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**::
 
     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!
+Thank you for contributing to PyFVCOM2!

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`.