Expand WCompBase docstrings

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
+    mermaid_version: 10.9.0
+    # napoleon_use_admonition_for_examples: true

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