Fixing docs warnings and docstring updates

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

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
 

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
+PyFVCOM2 builds on the Python scientific computing and geospatial ecosystem.
+Runtime and documentation dependencies are listed in the project metadata and
+documentation requirements.

doc/source/api/pyfvcom2.interpolation.rst

@@ -3,5 +3,6 @@ pyfvcom2.interpolation module
 
 .. automodule:: pyfvcom2.interpolation
    :members:
+   :exclude-members: InterpolationCoordinates
    :show-inheritance:
    :undoc-members:

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:

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'

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()
 
-

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

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]]])

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.

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:

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
-