From ecb2075b66afdb9ad59eb886541ab949a1ff05cc Mon Sep 17 00:00:00 2001
From: Rafael M Mudafort <rafmudaf@gmail.com>
Date: Fri, 8 Mar 2024 14:28:22 -0600
Subject: [PATCH] Expand WCompBase docstrings

---
 docs/_config.yml        |  5 +++--
 wcomp/base_interface.py | 43 ++++++++++++++++++++++++++++++++++++-----
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/docs/_config.yml b/docs/_config.yml
index c375392..f135d2a 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -33,7 +33,7 @@ sphinx:
   - 'sphinx.ext.viewcode'
   # - 'sphinx_autodoc_typehints'
   # - 'sphinxcontrib.autoyaml'
-  # - 'sphinx.ext.napoleon'               # Formats google and numpy docstring styles
+  - 'sphinx.ext.napoleon'               # Formats Google and NumPy docstring styles
   - 'sphinxcontrib.mermaid'
 
   config:
@@ -65,4 +65,5 @@ sphinx:
       # no-value
     autodoc_typehints: both
     # mermaid_output_format: png
-    mermaid_version: 10.9.0
\ No newline at end of file
+    mermaid_version: 10.9.0
+    # napoleon_use_admonition_for_examples: true
\ No newline at end of file
diff --git a/wcomp/base_interface.py b/wcomp/base_interface.py
index 90fdfc4..6282570 100644
--- a/wcomp/base_interface.py
+++ b/wcomp/base_interface.py
@@ -75,15 +75,48 @@ def vertical_profile_plot(
         x_coordinate: float,
         y_coordinate: float,
         zmax: float
-    ):
+    ) -> None:
         """
         This function produces a 1D plot of the velocity profile in the z-x plane
-        where z is normal to the ground and x is streamwise.
+        where z is normal to the ground and x is streamwise. A sample line is produced
+        from the ground to the height `zmax` at the location (`x_coordinate`, `y_coordinate`)
+        to sample the velocities.
+
+        To implement this function, the subclass should produce a line of the u-component of
+        velocities at the specified location and height. The {py:class}`wcomp.plotting.WakeProfile`
+        class should be used to store the data. Then, the {py:meth}`wcomp.plotting.plot_profile`
+        function should be used to produce the plot. A sample implementation is shown below.
 
         Args:
-            wind_direction (float): Wind direction to align the plot in the visualization in
-                degrees with West being 270 degrees and North being 0 degrees
-            y_coordinate (float): The lateral location to extract the plotted values
+            wind_direction (float): Incoming wind direction in degrees with West at 270 degrees.
+            x_coordinate (float): X-coordinate of the line to sample.
+            y_coordinate (float): Y-coordinate of the line to sample.
+            zmax (float): The end-point of the sample line in the vertical direction.
+                The line starts at the ground.
+
+        Raises:
+            NotImplementedError: This function must be implemented in a subclass
+
+        Example:
+            .. code-block:: python
+
+                # Call the wake model to produce the velocities at the sample line
+                u, v, w = wake_model()              # Note v and w are not used
+                x, y, z = wake_model.get_points()   # Get the coordinates of the sample points
+
+                # Create a WakeProfile object to store the data
+                profile = WakeProfile(y, u)
+
+                # Plot the profile
+                ax = plt.gca()      # Get the current pyplot axis to place the plot
+                plot_profile(
+                    profile,
+                    ax=ax,
+                    color=self.LINE_PLOT_COLOR,
+                    marker=self.LINE_PLOT_MARKER,
+                    linestyle=self.LINE_PLOT_LINESTYLE,
+                    label=self.LEGEND
+                )
         """
         raise NotImplementedError("WCompBase.vertical_profile_plot")