From cef514a1938a0305fb7d957fc85d1ad5fe3e4214 Mon Sep 17 00:00:00 2001 From: Michael Wathen Date: Tue, 25 Aug 2026 14:51:25 +0100 Subject: [PATCH] Fixing docs warnings and docstring updates --- .readthedocs.yaml | 2 +- README.md | 2 +- doc/source/acknowledgements.rst | 8 ++-- doc/source/api/pyfvcom2.interpolation.rst | 1 + doc/source/api/pyfvcom2.rst | 9 ----- doc/source/conf.py | 6 +-- pyfvcom2/fvcom_writer.py | 3 +- pyfvcom2/grid.py | 28 ++++---------- pyfvcom2/mesh_reader.py | 39 +++++++++----------- pyfvcom2/nest.py | 1 + pyfvcom2/ocean.py | 9 +++-- pyfvcom2/tide.py | 45 ++++++++--------------- 12 files changed, 59 insertions(+), 94 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 01c8bf4..9c6a7d4 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,7 +15,7 @@ build: sphinx: configuration: doc/source/conf.py builder: html - fail_on_warning: false + fail_on_warning: true # Optionally build your docs in additional formats such as PDF and ePub formats: diff --git a/README.md b/README.md index 665e3d9..090fa73 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ This project follows Python best practices: ## License -This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details. +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 diff --git a/doc/source/acknowledgements.rst b/doc/source/acknowledgements.rst index 09169b4..aedca57 100644 --- a/doc/source/acknowledgements.rst +++ b/doc/source/acknowledgements.rst @@ -4,14 +4,16 @@ Acknowledgements Funding ------- -TODO +Funding acknowledgements will be added as they are confirmed. Contributors ------------ -TODO +See the project repository for the current contributor history. Dependencies ------------ -TODO \ No newline at end of file +PyFVCOM2 builds on the Python scientific computing and geospatial ecosystem. +Runtime and documentation dependencies are listed in the project metadata and +documentation requirements. diff --git a/doc/source/api/pyfvcom2.interpolation.rst b/doc/source/api/pyfvcom2.interpolation.rst index 2c054a4..a8405c7 100644 --- a/doc/source/api/pyfvcom2.interpolation.rst +++ b/doc/source/api/pyfvcom2.interpolation.rst @@ -3,5 +3,6 @@ pyfvcom2.interpolation module .. automodule:: pyfvcom2.interpolation :members: + :exclude-members: InterpolationCoordinates :show-inheritance: :undoc-members: diff --git a/doc/source/api/pyfvcom2.rst b/doc/source/api/pyfvcom2.rst index 4fe2fa2..5b0d0ac 100644 --- a/doc/source/api/pyfvcom2.rst +++ b/doc/source/api/pyfvcom2.rst @@ -38,12 +38,3 @@ Submodules pyfvcom2.tide pyfvcom2.tide_reader pyfvcom2.weights_calculator - -Module contents ---------------- - -.. automodule:: pyfvcom2 - :members: - :show-inheritance: - :undoc-members: - :no-index: diff --git a/doc/source/conf.py b/doc/source/conf.py index d57d9f5..1b14188 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,4 +1,3 @@ -#!/usr/bin/env python2 # -*- coding: utf-8 -*- # # PyFVCOM2 documentation build configuration file. @@ -72,7 +71,7 @@ ] # Autodoc -napoleon_google_docstring = False +napoleon_google_docstring = True napoleon_use_ivar = True autodoc_mock_imports = [ 'cartopy', @@ -140,13 +139,12 @@ # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ['**.ipynb_checkpoints', 'apidocs/**'] -suppress_warnings = ['myst.xref_missing', 'docutils'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +todo_include_todos = False # Google analytics googleanalytics_id = 'G-5045ZREHMB' diff --git a/pyfvcom2/fvcom_writer.py b/pyfvcom2/fvcom_writer.py index 5108eb2..38c6639 100644 --- a/pyfvcom2/fvcom_writer.py +++ b/pyfvcom2/fvcom_writer.py @@ -32,7 +32,7 @@ def __init__(self, filename, dimensions, global_attributes=None, **kwargs): def add_variable(self, name, data, dimensions, attributes=None, format='f4', ncopts={}): """ - Create a `name' variable with the given `attributes' and `data'. + Create a ``name`` variable with the given ``attributes`` and ``data``. Parameters ---------- @@ -101,4 +101,3 @@ def __exit__(self, exc_type, exc_val, exc_tb): """ Tidy up the netCDF file handle. """ self.nc.close() - diff --git a/pyfvcom2/grid.py b/pyfvcom2/grid.py index 714ed5a..fd894e9 100644 --- a/pyfvcom2/grid.py +++ b/pyfvcom2/grid.py @@ -707,26 +707,14 @@ def connectivity(p, t): methods using triangular meshes. Args: - p : np.ndarray - Nx2 array of nodes coordinates, [[x1, y1], [x2, y2], etc.] - t : np.ndarray - Mx3 array of triangles as indices, [[n11, n12, n13], [n21, n22, n23], - etc.] + p: Nx2 array of node coordinates, ``[[x1, y1], [x2, y2], ...]``. + t: Mx3 array of triangles as indices, + ``[[n11, n12, n13], [n21, n22, n23], ...]``. Returns: - e : np.ndarray - Kx2 array of unique mesh edges - [[n11, n12], [n21, n22], etc.] - te : np.ndarray - Mx3 array of triangles as indices into e, [[e11, e12, e13], [e21, e22, - e23], etc.] - e2t : np.ndarray - Kx2 array of triangle neighbours for unique mesh edges - [[t11, t12], - [t21, t22], etc]. Each row has two entries corresponding to the - triangle numbers associated with each edge in e. Boundary edges have - e2t[i, 1] = -1. - bnd : np.ndarray, bool - Nx1 logical array identifying boundary nodes. p[i, :] is a boundary - node if bnd[i] = True. + tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: Unique mesh + edges, triangle edge indices, edge-to-triangle neighbours, and a + logical array identifying boundary nodes. Notes: Python translation of the MATLAB MESH2D connectivity function by Darren @@ -806,7 +794,7 @@ def _unique_rows(A, return_index=False, return_inverse=False): def find_connected_nodes(n, triangles): - """Return the IDs of the nodes surrounding node number `n'. + """Return the IDs of the nodes surrounding node number ``n``. Args: n : int @@ -855,7 +843,7 @@ def find_connected_nodes(n, triangles): def find_connected_elements(n, triangles): """ - Return the IDs of the elements connected to node number `n'. + Return the IDs of the elements connected to node number ``n``. Parameters ---------- diff --git a/pyfvcom2/mesh_reader.py b/pyfvcom2/mesh_reader.py index 3ac83bc..18978d8 100644 --- a/pyfvcom2/mesh_reader.py +++ b/pyfvcom2/mesh_reader.py @@ -120,7 +120,7 @@ def read_sms_mesh(mesh: str, nodestrings: Optional[bool] = False) -> MeshData: MeshData: Named tuple containing: - triangle (np.ndarray): Integer array of shape (nele, 3). Each triangle is composed of three points and this contains the three node numbers (stored in - nodes) which refer to the coordinates in `x' and `y' (see below). Values + nodes) which refer to the coordinates in ``x`` and ``y`` (see below). Values are python-indexed. - nodes (np.ndarray): Integer number assigned to each node. - X (np.ndarray): X coordinates of each grid node. @@ -217,9 +217,11 @@ def read_fvcom_mesh(mesh: str, obc_filename: Optional[str] = None, depth_filenam name should also contain '_grd' in the name e.g. 'my_file_grd.dat'. The file contains information about the triangle indicies and the x, y, z coodinates of the grid nodes. - The file header should be two lines: + The file header should be two lines:: + Node Number = nnn Cell Number = eee + Followed by 'element_index, tri1, tri2, tri3' for eee cells Followed by 'node_index, x, y, z' for nnn nodes obc_filename (str, optional): Full path to the FVCOM OBC file. This is @@ -231,7 +233,7 @@ def read_fvcom_mesh(mesh: str, obc_filename: Optional[str] = None, depth_filenam MeshData: Named tuple containing: - triangle (np.ndarray): Integer array of shape (ntri, 3). Each triangle is composed of three points and this contains the three node numbers (stored in - nodes) which refer to the coordinates in `x' and `y' (see below). + nodes) which refer to the coordinates in ``x`` and ``y`` (see below). - nodes (np.ndarray): Integer number assigned to each node. - X (np.ndarray): X coordinates of each grid node. - Y (np.ndarray): Y coordinates of each grid node. @@ -351,7 +353,7 @@ def read_smesh_mesh(mesh: str) -> MeshData: Returns: MeshData: Named tuple containing: - triangle (np.ndarray): Integer array of shape (ntri, 3). Each triangle is composed of three points and this contains the three node - numbers which refer to the coordinates in `x' and `y' (see below). + numbers which refer to the coordinates in ``x`` and ``y`` (see below). - nodes (Optional[np.ndarray]): None for smesh format (no node information available). - X (np.ndarray): X coordinates of each grid node. - Y (np.ndarray): Y coordinates of each grid node. @@ -405,7 +407,7 @@ def read_mike_mesh(mesh: str, flipZ: bool = True) -> MeshData: MeshData: Named tuple containing: - triangle (np.ndarray): Integer array of shape (ntri, 3). Each triangle is composed of three points and this contains the three node numbers (stored in - nodes) which refer to the coordinates in `x' and `y' (see below). Given as + nodes) which refer to the coordinates in ``x`` and ``y`` (see below). Given as a zero-indexed array. - nodes (np.ndarray): Integer number assigned to each node. - X (np.ndarray): X coordinates of each grid node. @@ -470,7 +472,7 @@ def read_gmsh_mesh(mesh: str) -> MeshData: MeshData: Named tuple containing: - triangle (np.ndarray): Integer array of shape (ntri, 3). Each triangle is composed of three points and this contains the three node numbers (stored in nodes) which - refer to the coordinates in `x' and `y' (see below). + refer to the coordinates in ``x`` and ``y`` (see below). - nodes (np.ndarray): Integer number assigned to each node. - X (np.ndarray): X coordinates of each grid node. - Y (np.ndarray): Y coordinates of each grid node. @@ -576,17 +578,11 @@ def read_fvcom_obc(obc): Read in an FVCOM open boundary file. Args: - obc : str - Path to the casename_obc.dat file from FVCOM. + obc: Path to the casename_obc.dat file from FVCOM. Returns: - nodes : np.ndarray - Node IDs (zero-indexed) for the open boundary. - types : np.ndarray - Open boundary node types (see the FVCOM manual for more information on - what these values mean). - count : np.ndarray - Open boundary node number. + tuple[np.ndarray, np.ndarray, np.ndarray]: Node IDs, open boundary node + types, and open boundary node numbers. """ @@ -600,17 +596,16 @@ def read_fvcom_obc(obc): def parse_obc_sections(obc_node_array, triangle): """ - Separates the open boundary nodes of a mesh into the separate contiguous open boundary segments + Separate open boundary nodes into contiguous open boundary segments. Args: - obc_node_array : array - Array of the nodes which are open boundary nodes, as nodes returned by read_fvcom_obc - triangle : 3xn array - Triangulation array of nodes, as triangle returned by read_fvcom_mesh + obc_node_array: Open boundary node IDs, as returned by + ``read_fvcom_obc``. + triangle: Triangulation array of nodes, as returned by + ``read_fvcom_mesh``. Returns: - nodestrings : list of arrays - A list of arrays, each of which is one contiguous section of open boundary + list[np.ndarray]: Contiguous open boundary node sections. """ all_edges = np.vstack([triangle[:, 0:2], triangle[:, 1:], triangle[:, [0, 2]]]) diff --git a/pyfvcom2/nest.py b/pyfvcom2/nest.py index 8c1e06d..e4cf34e 100644 --- a/pyfvcom2/nest.py +++ b/pyfvcom2/nest.py @@ -840,6 +840,7 @@ def apply_ramp(self, ramp_length: float, initial_ts: Optional[list] = None, from for temperature and salinity. If None those variables are not ramped. ramp_type: Shape of the ramp function. One of: + - 'cosine' (default): half-cosine, C¹ continuous at both t=0 and t=ramp_length. Reaches full amplitude at t=ramp_length. - 'tanh': hyperbolic tangent, C∞ everywhere but asymptotic. diff --git a/pyfvcom2/ocean.py b/pyfvcom2/ocean.py index c2b3c86..f63a151 100644 --- a/pyfvcom2/ocean.py +++ b/pyfvcom2/ocean.py @@ -3,10 +3,12 @@ MATLAB toolboxes as well as from ocean_funcs.ncl, which in turn has taken them from the CSIRO SEAWATER (now GSW) MATLAB toolbox. -The NCL code can be found at: +The NCL code can be found at:: + http://www.ncl.ucar.edu/Support/talk_archives/2013/att-1501/ocean_funcs.ncl__size_15540__creation-date_ -The MATLAB toolboxes used includes: +The MATLAB toolboxes used includes:: + http://www.cmar.csiro.au/datacentre/ext_docs/seawater.htm http://mooring.ucsd.edu/software/matlab/doc/toolbox/ocean/ http://www.mbari.org/staff/etp3/ocean1.htm @@ -31,7 +33,8 @@ 404-6. The relative humidity from dew point temperature and ambient temperature is -taken from: +taken from:: + http://www.vaisala.com/Vaisala%20Documents/Application%20notes/Humidity_Conversion_Formulas_B210973EN-F.pdf Provides functions: diff --git a/pyfvcom2/tide.py b/pyfvcom2/tide.py index 7fb1a9e..a9b58e7 100644 --- a/pyfvcom2/tide.py +++ b/pyfvcom2/tide.py @@ -190,26 +190,18 @@ def predict_tide( using the provided tidal constituent amplitudes and phases. Args: - datetimes : np.ndarray - Array of datetime objects for prediction times. - interval : float - Time interval between datetimes in days. - constituents : list[str] - List of tidal constituent names to read. - amplitudes : np.ndarray - Amplitude of the relevant constituents shaped [nlocs, nconst]. - phases : np.ndarray - Array of the phase of the relevant constituents shaped [nlocs, nconst]. - latitudes : np.ndarray - Latitudes of the positions to predict. - parallel : bool, optional - Whether to run the predictions in parallel using multiprocessing. Default is True. - pool_size : int, optional - Number of parallel processes to use. If 1, runs serially. Default is - 1. + datetimes: Array of datetime objects for prediction times. + constituents: List of tidal constituent names to read. + amplitudes: Amplitudes of the relevant constituents shaped + ``[nlocs, nconst]``. + phases: Phases of the relevant constituents shaped ``[nlocs, nconst]``. + latitudes: Latitudes of the positions to predict. + parallel: Whether to run the predictions in parallel using + multiprocessing. Default is True. + pool_size: Number of parallel processes to use. If 1, runs serially. + Returns: - results : list[np.ndarray] - List of predicted zeta time series arrays for each location. + list[np.ndarray]: Predicted zeta time series arrays for each location. """ const_indices = np.asarray( [ut_constants["const"]["name"].tolist().index(i) for i in constituents] @@ -267,17 +259,13 @@ def reconstruct_wrapper(args: tuple) -> np.ndarray: series at the given latitude. Args: - args : tuple - Tuple of (lats, times, coef, amplitudes, phases) where: - - lats: Latitude of the position to predict. - - times: Array of datenums (days since MJD zero point). - - coef: UTide coefficients Bunch. - - amplitudes: Amplitude of the relevant constituents shaped [nconst]. - - phases: Phase of the relevant constituents shaped [nconst]. + args: Tuple of ``(lats, times, coef, amplitudes, phases)`` where + ``lats`` is the latitude, ``times`` are datenums, ``coef`` is the + UTide coefficients bunch, and ``amplitudes`` and ``phases`` are + shaped ``[nconst]``. Returns: - zeta : np.ndarray - Time series of surface elevations. + np.ndarray: Time series of surface elevations. Notes ----- @@ -1014,4 +1002,3 @@ def _load_full_timeseries(self, var: str, zlev: int = None) -> np.ndarray: data[global_idxs, :] = slice_ return data -