Raise documentation and examples errors in CI (#736)

* Remove unused modules in `floris.tools`

* Fix broken import paths

* Removed unused reference file

* Disable auto-doc for private functions

* Fix references format in CC docstring

* isort

* Add Em Gauss page to toc

* Spell check in docstrings

* Raise an error when notebooks fail in docs build

* Run the examples far away from the top directory

This ensures there’s no reliance on the repo struture to find source files

* Expand Python version checks

* Pin docs dependencies versions

Jupyter Book v0.14 supports setting this:
nb_execution_show_tb: true
nb_execution_raise_on_error: true

And sphinx-book-theme 0.4.0rc1 is the required version for JupyterBook v0.14. Note that there is an incompatibility with FLORIS docs and JupyterBook v0.15, sphinx-book-theme v1.0.

* Fix configuration parameter

* Use index for home page

Mostly just to make the docs build on GitHub to test that it exits on error

Author: rafmudaf

.github/workflows/check-working-examples.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.9", "3.10", "3.11"]
         os: [ubuntu-latest] #, macos-latest, windows-latest]
       fail-fast: False
 
@@ -25,9 +25,14 @@ jobs:
         pip install nbconvert  # For converting Jupyter notebook to python script in the next step
     - name: Run examples
       # Run all examples and test that they finish successfully. Do not evaluate the results.
+      # Copy the examples to a new directory outside of the repo to ensure that there is no
+      # reliance on the repo directory structure.
       run: |
 
-        cd examples/
+        mkdir -p temp1/temp2/temp3
+        cp -r examples/ temp1/temp2/temp3/.
+        cd temp1/temp2/temp3/examples/
+
         error_found=0  # 0 is false
         error_results="Error in example:"
 

.github/workflows/continuous-integration-workflow.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         os: [ubuntu-latest] #, macos-latest, windows-latest]
       fail-fast: False
     env:

docs/_config.yml

@@ -44,13 +44,17 @@ 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:
     html_theme: sphinx_book_theme
     templates_path:
     - '_templates'
     language: 'python'
+    nb_execution_show_tb: true          # Shows the stack trace in stdout; its suppressed otherwise.
+    nb_execution_raise_on_error: true   # Stops the Sphinx build if there is an error in a notebook. See https://github.com/executablebooks/jupyter-book/issues/2011
+    suppress_warnings:
+    - etoc.toctree                      # autodoc output contains toctrees, so suppress this warning. See https://github.com/executablebooks/sphinx-external-toc/issues/36
     autoyaml_level: 3
     autosummary_generate: true
 
@@ -60,7 +64,7 @@ sphinx:
       members: true
       member-order: bysource
       undoc-members: true
-      private-members: true
+      private-members: false
       # special-members: true
       # inherited-members
       # show-inheritance

docs/_toc.yml

@@ -2,11 +2,10 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: intro
+root: index
 parts:
   - caption: Getting Started
     chapters:
-    # - file: intro
     - file: installation
 
   - caption: User Reference
@@ -21,6 +20,8 @@ parts:
   - caption: Theory and Background
     chapters:
     - file: wake_models
+      sections:
+      - file: empirical_gauss_model
     - file: bibliography
 
   - caption: Developer Reference

docs/intro.md renamed to docs/index.md

@@ -259,7 +259,8 @@ @article{bastankhah_2021
   publisher={Cambridge University Press},
   author={Bastankhah, Majid and Welch, Bridget L. and Martínez-Tossas, Luis A. and King, Jennifer and Fleming, Paul},
   year={2021},
-  pages={A53}}
+  pages={A53}
+}
 
 @Article{bay_2022,
 AUTHOR = {Bay, C. J. and Fleming, P. and Doekemeijer, B. and King, J. and Churchfield, M. and Mudafort, R.},

docs/reference.md

@@ -200,7 +200,7 @@ def check_deprecated_inputs(self):
     def initialize_domain(self):
         """Initialize solution space prior to wake calculations"""
 
-        # Initialize field quanitities; doing this immediately prior to doing
+        # Initialize field quantities; doing this immediately prior to doing
         # the calculation step allows for manipulating inputs in a script
         # without changing the data structures
         self.flow_field.initialize_velocity_field(self.grid)

docs/references.bib

@@ -134,7 +134,7 @@ def initialize_velocity_field(self, grid: Grid) -> None:
             * (grid.z_sorted) ** (self.wind_shear - 1)
         )
 
-        # If no hetergeneous inflow defined, then set all speeds ups to 1.0
+        # If no heterogeneous inflow defined, then set all speeds ups to 1.0
         if self.het_map is None:
             speed_ups = 1.0
 

floris/simulation/floris.py

@@ -394,7 +394,7 @@ def axial_induction(
         turbine_type_map: (NDArrayObject[wd, ws, turbines]): The Turbine type definition
             for each turbine.
         ix_filter (NDArrayFilter | Iterable[int] | None, optional): The boolean array, or
-            integer indices (as an aray or iterable) to filter out before calculation.
+            integer indices (as an array or iterable) to filter out before calculation.
             Defaults to None.
 
     Returns:

floris/simulation/flow_field.py

@@ -207,7 +207,7 @@ def axial_induction_multidim(
         turbine_type_map: (NDArrayObject[wd, ws, turbines]): The Turbine type definition
             for each turbine.
         ix_filter (NDArrayFilter | Iterable[int] | None, optional): The boolean array, or
-            integer indices (as an aray or iterable) to filter out before calculation.
+            integer indices (as an array or iterable) to filter out before calculation.
             Defaults to None.
 
     Returns:
@@ -270,7 +270,7 @@ def multidim_Ct_down_select(
         conditions (dict): The conditions at which to determine which Ct interpolant to use.
 
     Returns:
-        NDArray: The downselected Ct interpolants for the selected conditions.
+        NDArray: The down selected Ct interpolants for the selected conditions.
     """
     downselect_turbine_fCts = np.empty_like(turbine_fCts)
     # Loop over the wind directions, wind speeds, and turbines, finding the Ct interpolant
@@ -307,7 +307,7 @@ def multidim_power_down_select(
         conditions (dict): The conditions at which to determine which Ct interpolant to use.
 
     Returns:
-        NDArray: The downselected power interpolants for the selected conditions.
+        NDArray: The down selected power interpolants for the selected conditions.
     """
     downselect_power_interps = np.empty_like(power_interps)
     # Loop over the wind directions, wind speeds, and turbines, finding the power interpolant

floris/simulation/turbine.py

@@ -29,7 +29,7 @@ def prepare_function(self) -> dict:
     def function(self, wake_field: np.ndarray, velocity_field: np.ndarray):
         """
         Combines the base flow field with the velocity deficits
-        using freestream linear superpostion. In other words, the wake
+        using freestream linear superposition. In other words, the wake
         field and base fields are simply added together.
 
         Args:

floris/simulation/turbine_multi_dim.py

@@ -35,7 +35,7 @@ def prepare_function(self) -> dict:
 
     def function(self, wake_field: np.ndarray, velocity_field: np.ndarray):
         """
-        Incorporates the velicty deficits into the base flow field by
+        Incorporates the velocity deficits into the base flow field by
         selecting the maximum of the two for each point.
 
         Args:

floris/simulation/wake_combination/fls.py

@@ -28,7 +28,7 @@ def prepare_function(self) -> dict:
 
     def function(self, wake_field: np.ndarray, velocity_field: np.ndarray):
         """
-        Combines the base flow field with the velocity defecits
+        Combines the base flow field with the velocity deficits
         using sum of squares.
 
         Args:

floris/simulation/wake_combination/max.py

@@ -29,7 +29,7 @@
 class EmpiricalGaussVelocityDeflection(BaseModel):
     """
     The Empirical Gauss deflection model is based on the form of previous the
-    Guass deflection model (see :cite:`bastankhah2016experimental` and
+    Gauss deflection model (see :cite:`bastankhah2016experimental` and
     :cite:`King2019Controls`) but simplifies the formulation for simpler
     tuning and more independence from the velocity deficit model.
 
@@ -38,10 +38,10 @@ class EmpiricalGaussVelocityDeflection(BaseModel):
         in `parameter_dictionary`. Possible key-value pairs include:
 
             -   **horizontal_deflection_gain_D** (*float*): Gain for the
-                maximum (y-direction) deflection acheived far downstream
+                maximum (y-direction) deflection achieved far downstream
                 of a yawed turbine.
             -   **vertical_deflection_gain_D** (*float*): Gain for the
-                maximum vertical (z-direction) deflection acheived at a
+                maximum vertical (z-direction) deflection achieved at a
                 far downstream location due to rotor tilt. Specifying as
                 -1 will mean that vertical deflections due to tilt match
                 horizontal deflections due to yaw.
@@ -101,7 +101,7 @@ def function(
             mixing_i (np.array): The wake-induced mixing term for the
                 ith turbine.
             ct_i (np.array): Thrust coefficient for the ith turbine (-).
-            rotor_diameter_i (np.array): Rotor diamter for the ith
+            rotor_diameter_i (np.array): Rotor diameter for the ith
                 turbine (m).
 
             x (np.array): Streamwise direction grid coordinates of the

floris/simulation/wake_combination/sosfs.py

@@ -29,7 +29,7 @@
 @define
 class JimenezVelocityDeflection(BaseModel):
     """
-    Jiménez wake deflection model, dervied from
+    Jiménez wake deflection model, derived from
     :cite:`jdm-jimenez2010application`.
 
     References:
@@ -67,7 +67,7 @@ def function(
         x: np.ndarray,
     ):
         """
-        Calcualtes the deflection field of the wake in relation to the yaw of
+        Calculates the deflection field of the wake in relation to the yaw of
         the turbine. This is coded as defined in [1].
 
         Args:

floris/simulation/wake_deflection/empirical_gauss.py

@@ -34,14 +34,14 @@
 class CumulativeGaussCurlVelocityDeficit(BaseModel):
     """
     The cumulative curl model is an implementation of the model described in
-    :cite:`gdm-bay_2022`, which itself is based on the cumulative model of
-    :cite:`bastankhah_2021`
+    :cite:`cc-bay_2022`, which itself is based on the cumulative model of
+    :cite:`cc-bastankhah_2021`.
 
     References:
-    .. bibliography:: /references.bib
-        :style: unsrt
-        :filter: docname in docnames
-        :keyprefix: gdm-
+        .. bibliography:: /references.bib
+            :style: unsrt
+            :filter: docname in docnames
+            :keyprefix: cc-
     """
 
     a_s: float = field(default=0.179367259)
@@ -135,8 +135,8 @@ def function(
             y_coord_m = y_coord[:, :, m:m+1]
             z_coord_m = z_coord[:, :, m:m+1]
 
-            # For computing crossplanes, we don't need to compute downstream
-            # turbines from out crossplane position.
+            # For computing cross planes, we don't need to compute downstream
+            # turbines from out cross plane position.
             if x_coord[:, :, m:m+1].size == 0:
                 break
 

floris/simulation/wake_deflection/jimenez.py

@@ -227,7 +227,7 @@ def function(
                 sigma_y0,
                 sigma_z0
             )
-            # Normalize to match end of acuator disk model tube
+            # Normalize to match end of actuator disk model tube
             C_mirr = C_mirr / (8 * self.sigma_0_D**2)
 
             # ASSUME sum-of-squares superposition for the real and mirror wakes

floris/simulation/wake_velocity/cumulative_gauss_curl.py

@@ -119,7 +119,7 @@ def function(
 
         # Compute the velocity deficit in the NEAR WAKE region
         # ONLY If there are points within the near wake boundary
-        # TODO: for the turbinegrid, do we need to do this near wake calculation at all?
+        # TODO: for the TurbineGrid, do we need to do this near wake calculation at all?
         #       same question for any grid with a resolution larger than the near wake region
         if np.sum(near_wake_mask):
 

floris/simulation/wake_velocity/empirical_gauss.py

@@ -104,7 +104,7 @@ def function(
         downstream_mask = (x_i - x >= self.NUM_EPS)
         x_dist = (x_i - x) * downstream_mask / rotor_diameters
 
-        # Radial distance between turbine i and the centerlines of wakes from all
+        # Radial distance between turbine i and the center lines of wakes from all
         # real/image turbines
         r_dist = np.sqrt((y_i - (y + deflection_field)) ** 2 + (z_i - z) ** 2)
         r_dist_image = np.sqrt((y_i - (y + deflection_field)) ** 2 + (z_i - (-z)) ** 2)

floris/simulation/wake_velocity/gauss.py

@@ -31,9 +31,9 @@
     >>> dir(floris.tools)
     ['__builtins__', '__cached__', '__doc__', '__file__', '__loader__',
     '__name__', '__package__', '__path__', '__spec__', 'cut_plane',
-    'floris_interface', 'flow_data',
+    'floris_interface',
     'layout_functions', 'optimization', 'plotting', 'power_rose',
-    'rews', 'sowfa_utilities', 'visualization', 'wind_rose']
+    'rews', 'visualization', 'wind_rose']
 """
 
 from .floris_interface import FlorisInterface
@@ -52,14 +52,12 @@
 # from floris.tools import (
     # cut_plane,
     # floris_interface,
-    # flow_data,
     # interface_utilities,
     # layout_functions,
     # optimization,
     # plotting,
     # power_rose,
     # rews,
-    # sowfa_utilities,
     # visualization,
     # wind_rose,
 # )