wip docs with notebook example

docs/source/conf.py

@@ -3,26 +3,61 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../.."))
+
+# import mock
+
+# MOCK_MODULES = ['numpy', 'matplotlib', 'pandas']
+# for mod_name in MOCK_MODULES:
+#     sys.modules[mod_name] = mock.Mock()
+
+
+import oceans_sf
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Oceans SF'
-copyright = '2024, Cassidy Wagner'
-author = 'Cassidy Wagner'
-release = '0.1.0'
+project = "Oceans SF"
+copyright = "2024, Cassidy Wagner"
+author = "Cassidy Wagner"
+release = "0.1.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
-
-templates_path = ['_templates']
-exclude_patterns = []
-
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "numpydoc",
+    "nbsphinx",
+]
+templates_path = ["_templates"]
+exclude_patterns = ["tests/test_*", "test_*"]
 
+# autosummary_generate = True
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+# html_static_path = ["./build/html/_static"]
+
+# -- Intersphinx mapping --
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}

docs/source/examples.rst

@@ -1,4 +1,58 @@
-Example use cases
+Examples
 ========
 
-A sample dataset is provided
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ex1
+
+.. A sample dataset is provided in ``oceans_sf/examples/sample_data`` which we 
+.. use below to demonstrate oceans_sf functionality.
+
+.. Loading and preparing HDF5 data for oceans_sf
+.. *********************************************
+
+.. .. code-block:: python
+   
+..    import h5py
+   
+..    f = h5py.File('oceans_sf/examples/sample_data/snapshot1.jld2', 'r')
+..    grid = f['grid']
+..    snapshots = f['snapshots']
+
+..    x = grid['x']
+..    y = grid['y']
+..    u = snapshots['u']
+..    v = snapshots['v']
+
+.. Advective velocity-based structure functions
+.. ********************************************
+
+.. This snippet returns a dictionary of advective velocity-based structure functions 
+.. for two directions, meridional and zonal. The separation distances in x and y are also returned.
+
+.. .. code-block:: python
+   
+..    import oceans_sf as ocsf
+
+..    sf = ocsf.generate_structure_functions(u,v,x,y)
+
+..    print(sf)
+
+
+.. Advective velocity structure functions
+.. **************************************
+
+.. .. code-block:: python
+
+..    Z, M, XD, YD = ocsf.advection_velocity(u, v, x, y)
+
+.. Advective vorticity structure functions
+.. ***************************************
+
+.. Multiple snapshots of data
+.. **************************
+
+.. Plotting cascade rates
+.. **********************

docs/source/index.rst

@@ -3,20 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Oceans SF's documentation!
+oceans_sf Documentation
 =====================================
 
+oceans_sf is a Python package for estimating structure functions from oceanographic data.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    overview
    installation
    examples
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   modules

docs/source/installation.rst

@@ -1,4 +1,4 @@
 Installation instructions
-========================
+=========================
 
 Install instructions

docs/source/modules.rst

@@ -0,0 +1,7 @@
+Functions
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   oceans_sf

docs/source/oceans_sf.rst

@@ -0,0 +1,9 @@
+oceans\_sf package
+
+oceans\_sf function documentation
+---------------------------------
+
+.. automodule:: oceans_sf
+   :members:
+   :undoc-members:
+   :show-inheritance:

oceans_sf/bin_data.py

@@ -6,8 +6,8 @@ def bin_data(dd, sf, nbins):
     Bins the data based on the separation distances and calculates the the bin-averaged
     structure functions.
 
-    Args
-    ----
+    Parameters
+    ----------
     dd (array-like): The separation distances to be binned.
     sf (array-like): The structure functions that will be bin-averaged.
     nbins (int): The number of bins to create.

oceans_sf/calculate_advection.py

@@ -18,8 +18,8 @@ def calculate_advection(
     velocity field. If the velocity advection is skipped or a scalar field is not
     provided, the relevant dictionary key will return None.
 
-    Args:
-    ----
+    Parameters
+    ----------
         u (ndarray): The u-component of velocity.
         v (ndarray): The v-component of velocity.
         x (ndarray): The x-coordinates of the grid.
@@ -31,7 +31,7 @@ def calculate_advection(
         grid_type (str, optional): The type of grid. Defaults to "uniform".
         scalar (numpy.ndarray, optional): Array of scalar values. Defaults to None.
 
-    Returns:
+    Returns
     -------
         tuple or ndarray: A tuple of advection components (eastward_advection,
         northward_advection) if scalar is not provided, otherwise returns an ndarray

oceans_sf/calculate_separation_distances.py

@@ -6,8 +6,8 @@ def calculate_separation_distances(x, y, x_shift, y_shift, grid_type="uniform"):
     """
     Calculate the separation distances between two points.
 
-    Args
-    ----
+    Parameters
+    ----------
     x (float): The x-coordinate of the first point.
     y (float): The y-coordinate of the first point.
     x_shift (float): The x-coordinate of the second point.

oceans_sf/calculate_structure_function.py

@@ -20,8 +20,8 @@ def calculate_structure_function(
     Calculate structure function, either advective or traditional.
     Supports velocity-based structure functions and scalar-based structure functions.
 
-    Args:
-    ----
+    Parameters
+    ----------
         u (numpy.ndarray): Array of u velocities.
         v (numpy.ndarray): Array of v velocities.
         adv_e (numpy.ndarray): Array of eastward advection values.
@@ -43,7 +43,7 @@ def calculate_structure_function(
         boundary (str, optional): Boundary condition for shifting arrays.
         Defaults to "Periodic".
 
-    Returns:
+    Returns
     -------
         dict: A dictionary containing the advection velocity structure functions and
         scalar structure functions (if applicable).

oceans_sf/generate_structure_functions.py

@@ -30,8 +30,8 @@ def generate_structure_functions(  # noqa: C901
     functions. Defaults to calculating the velocity-based advective structure functions
     for the x (zonal) and y (meridional) directions.
 
-    Args:
-    ----
+    Parameters
+    ----------
         u (ndarray): 2D array of u velocity components.
         v (ndarray): 2D array of v velocity components.
         x (ndarray): 1D array of x-coordinates.
@@ -53,7 +53,7 @@ def generate_structure_functions(  # noqa: C901
         Defaults to "uniform".
         nbins (int, optional): Number of bins for binning the data. Defaults to 10.
 
-    Returns:
+    Returns
     -------
         dict: Dictionary containing the requested structure functions and separation
         distances for the x- and y-direction (zonal and meridional, respectively).
@@ -103,7 +103,7 @@ def generate_structure_functions(  # noqa: C901
             SF_m_trad_scalar = np.zeros(len(sep_m) + 1)
 
     # Iterate over separations right and down
-    for down, right in zip(sep_m, sep_z, strict=False):
+    for down, right in zip(sep_m, sep_z):
         xroll = shift_array1d(x, shift_by=right, boundary=boundary)
         yroll = shift_array1d(y, shift_by=down, boundary=boundary)
 

oceans_sf/shift_array1d.py

@@ -6,8 +6,8 @@ def shift_array1d(input_array, shift_by=1, boundary="Periodic"):
     Shifts 1D array by an integer amount and returns the shifted array.
     Either wraps the array or shifts and pads with NaNs.
 
-    Args:
-    ----
+    Parameters
+    ----------
         input_array (array_like): 1-dimensional array to be shifted.
         shift_by (int, optional): Shift amount for array. For periodic data should be
         less than len(input_array)/2 and less than len(input_array) for other boundary
@@ -16,7 +16,7 @@ def shift_array1d(input_array, shift_by=1, boundary="Periodic"):
         Periodic boundary conditions will wrap the array, otherwise the array will be
         padded with NaNs. Defaults to "Periodic".
 
-    Returns:
+    Returns
     -------
         shifted_array: 1D array shifted by requested integer amount
     """

oceans_sf/shift_array2d.py

@@ -6,24 +6,29 @@ def shift_array2d(input_array, shift_right=1, shift_down=1, boundary="Periodic")
     Shifts 2D array right and down by the specified integer amounts and returns
     the shifted arrays. Either wraps the array or shifts and pads with NaNs.
 
-    Args:
-    ----
-        input_array (array_like): 2-dimensional array to be shifted.
-        shift_right (int, optional): Shift amount for rightward shift. For periodic data
-        should be less than half the row length and less than the row length for
-        other boundary conditions. Defaults to 1.
-        shift_down (int, optional): Shift amount for downward shift. For periodic data
-        should be less than half the column length and less than the column length for
-        other boundary conditions. Defaults to 1.
-        boundary (str, optional): Boundary condition for input array.
-        Periodic boundary conditions will wrap the array, otherwise the array will be
-        padded with NaNs. Defaults to "Periodic".
+    Parameters
+    ----------
+        input_array: array_like
+            2-dimensional array to be shifted.
+        shift_right: int, optional
+            Shift amount for rightward shift. For periodic data should be less than
+            half the row length and less than the row length for other boundary
+            conditions. Defaults to 1.
+        shift_down: int, optional
+            Shift amount for downward shift. For periodic data should be less than
+            half the column length and less than the column length for other boundary
+            conditions. Defaults to 1.
+        boundary: str, optional
+            Boundary condition for input array. Periodic boundary conditions will wrap
+            the array, otherwise the array will be padded with NaNs. Defaults to
+            "Periodic".
 
-    Returns:
+    Returns
     -------
-        shifted_right_array: 2D array shifted to the right by the specified integer
-        amount
-        shifted_down_array: 2D array shifted down by the specified integer amount
+        shifted_right_array
+            2D array shifted to the right by the specified integer amount
+        shifted_down_array
+            2D array shifted down by the specified integer amount
     """
     shifted_right_array = np.full(np.shape(input_array), np.nan)
     shifted_down_array = np.full(np.shape(input_array), np.nan)