Docstring improvements

wind-python · Jun 10, 2019 · 18c26a3 · 18c26a3
1 parent 26ab6e8
commit 18c26a3
Show file tree

Hide file tree

Showing 13 changed files with 84 additions and 86 deletions.
diff --git a/example/modelchain_example.py b/example/modelchain_example.py
@@ -56,7 +56,7 @@ def get_weather_data(filename='weather.csv', **kwargs):
 
     Returns
     -------
-    weather_df : :pandas:`pandas.DataFrame<frame>`
+    :pandas:`pandas.DataFrame<frame>`
             DataFrame with time series for wind speed `wind_speed` in m/s,
             temperature `temperature` in K, roughness length `roughness_length`
             in m, and pressure `pressure` in Pa.

diff --git a/example/turbine_cluster_modelchain_example.py b/example/turbine_cluster_modelchain_example.py
@@ -47,7 +47,7 @@ def initialize_wind_farms(my_turbine, e126):
 
     Returns
     -------
-    Tuple (:class:`~.wind_farm.WindFarm`, :class:`~.wind_farm.WindFarm`)
+    tuple(:class:`~.wind_farm.WindFarm`, :class:`~.wind_farm.WindFarm`)
 
     """
 

diff --git a/windpowerlib/density.py b/windpowerlib/density.py
@@ -18,26 +18,26 @@ def barometric(pressure, pressure_height, hub_height, temperature_hub_height):
 
     Parameters
     ----------
-    pressure : pandas.Series or numpy.array
+    pressure : :pandas:`pandas.Series<series>` or numpy.array
         Air pressure in Pa.
     pressure_height : float
         Height in m for which the parameter `pressure` applies.
     hub_height : float
         Hub height of wind turbine in m.
-    temperature_hub_height : pandas.Series or numpy.array
+    temperature_hub_height : :pandas:`pandas.Series<series>` or numpy.array
         Air temperature at hub height in K.
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Density of air at hub height in kg/m³.
         Returns a pandas.Series if one of the input parameters is a
         pandas.Series.
 
     Notes
     -----
 
-    The following equation is used [1]_, [2]_ :
+    The following equation is used [1]_ [2]_ :
 
     .. math:: \rho_{hub}=\left(p/100-\left(h_{hub}-h_{p,data}\right)
        \cdot\frac{1}{8}\right)\cdot \frac{\rho_0 T_0\cdot 100}{p_0 T_{hub}}
@@ -76,25 +76,25 @@ def ideal_gas(pressure, pressure_height, hub_height, temperature_hub_height):
 
     Parameters
     ----------
-    pressure : pandas.Series or numpy.array
+    pressure : :pandas:`pandas.Series<series>` or numpy.array
         Air pressure in Pa.
     pressure_height : float
         Height in m for which the parameter `pressure` applies.
     hub_height : float
         Hub height of wind turbine in m.
-    temperature_hub_height : pandas.Series or numpy.array
+    temperature_hub_height : :pandas:`pandas.Series<series>` or numpy.array
         Air temperature at hub height in K.
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Density of air at hub height in kg/m³.
         Returns a pandas.Series if one of the input parameters is a
         pandas.Series.
 
     Notes
     -----
-    The following equations are used [1]_, [2]_, [3]_:
+    The following equations are used [1]_ [2]_ [3]_:
 
     .. math:: \rho_{hub}=p_{hub}/ (R_s T_{hub})
 

diff --git a/windpowerlib/modelchain.py b/windpowerlib/modelchain.py
@@ -18,27 +18,27 @@ class ModelChain(object):
 
     Parameters
     ----------
-    power_plant : WindTurbine
+    power_plant : :class:`~.wind_turbine.WindTurbine`
         A :class:`~.wind_turbine.WindTurbine` object representing the wind
         turbine.
-    wind_speed_model : string
+    wind_speed_model : str
         Parameter to define which model to use to calculate the wind speed at
         hub height. Valid options are 'logarithmic', 'hellman' and
         'interpolation_extrapolation', 'log_interpolation_extrapolation'.
         Default: 'logarithmic'.
-    temperature_model : string
+    temperature_model : str
         Parameter to define which model to use to calculate the temperature of
         air at hub height. Valid options are 'linear_gradient' and
         'interpolation_extrapolation'. Default: 'linear_gradient'.
-    density_model : string
+    density_model : str
         Parameter to define which model to use to calculate the density of air
         at hub height. Valid options are 'barometric', 'ideal_gas' and
         'interpolation_extrapolation'. Default: 'barometric'.
-    power_output_model : string
+    power_output_model : str
         Parameter to define which model to use to calculate the turbine power
         output. Valid options are 'power_curve' and 'power_coefficient_curve'.
         Default: 'power_curve'.
-    density_correction : boolean
+    density_correction : bool
         If the parameter is True the density corrected power curve is used for
         the calculation of the turbine power output. Default: False.
     obstacle_height : float
@@ -51,7 +51,7 @@ class ModelChain(object):
 
     Attributes
     ----------
-    power_plant : WindTurbine
+    power_plant : :class:`~.wind_turbine.WindTurbine`
         A :class:`~.wind_turbine.WindTurbine` object representing the wind
         turbine.
     wind_speed_model : str
@@ -71,7 +71,7 @@ class ModelChain(object):
         Parameter to define which model to use to calculate the turbine power
         output. Valid options are 'power_curve' and 'power_coefficient_curve'.
         Default: 'power_curve'.
-    density_correction : boolean
+    density_correction : bool
         If the parameter is True the density corrected power curve is used for
         the calculation of the turbine power output. Default: False.
     hellman_exp : float
@@ -81,7 +81,7 @@ class ModelChain(object):
     obstacle_height : float
         Height of obstacles in the surrounding area of the wind turbine in m.
         Set `obstacle_height` to zero for wide spread obstacles. Default: 0.
-    power_output : pandas.Series
+    power_output : :pandas:`pandas.Series<series>`
         Electrical power output of the wind turbine in W.
 
     Examples
@@ -130,7 +130,7 @@ def temperature_hub(self, weather_df):
 
         Parameters
         ----------
-        weather_df : pandas.DataFrame
+        weather_df : :pandas:`pandas.DataFrame<frame>`
             DataFrame with time series for temperature `temperature` in K.
             The columns of the DataFrame are a MultiIndex where the first level
             contains the variable name (e.g. temperature) and the second level
@@ -141,7 +141,7 @@ def temperature_hub(self, weather_df):
 
         Returns
         -------
-        temperature_hub : pandas.Series or numpy.array
+        :pandas:`pandas.Series<series>` or numpy.array
             Temperature of air in K at hub height.
 
         Notes
@@ -185,7 +185,7 @@ def density_hub(self, weather_df):
 
         Parameters
         ----------
-        weather_df : pandas.DataFrame
+        weather_df : :pandas:`pandas.DataFrame<frame>`
             DataFrame with time series for temperature `temperature` in K,
             pressure `pressure` in Pa and/or density `density` in kg/m³,
             depending on the `density_model` used.
@@ -198,7 +198,7 @@ def density_hub(self, weather_df):
 
         Returns
         -------
-        density_hub : pandas.Series or numpy.array
+        :pandas:`pandas.Series<series>` or numpy.array
             Density of air in kg/m³ at hub height.
 
         Notes
@@ -252,7 +252,7 @@ def wind_speed_hub(self, weather_df):
 
         Parameters
         ----------
-        weather_df : pandas.DataFrame
+        weather_df : :pandas:`pandas.DataFrame<frame>`
             DataFrame with time series for wind speed `wind_speed` in m/s and
             roughness length `roughness_length` in m.
             The columns of the DataFrame are a MultiIndex where the first level
@@ -264,7 +264,7 @@ def wind_speed_hub(self, weather_df):
 
         Returns
         -------
-        wind_speed_hub : pandas.Series or numpy.array
+        :pandas:`pandas.Series<series>` or numpy.array
             Wind speed in m/s at hub height.
 
         Notes
@@ -324,14 +324,14 @@ def calculate_power_output(self, wind_speed_hub, density_hub):
 
         Parameters
         ----------
-        wind_speed_hub : pandas.Series or numpy.array
+        wind_speed_hub : :pandas:`pandas.Series<series>` or numpy.array
             Wind speed at hub height in m/s.
-        density_hub : pandas.Series or numpy.array
+        density_hub : :pandas:`pandas.Series<series>` or numpy.array
             Density of air at hub height in kg/m³.
 
         Returns
         -------
-        pandas.Series
+        :pandas:`pandas.Series<series>`
             Electrical power output of the wind turbine in W.
 
         """
@@ -370,7 +370,7 @@ def run_model(self, weather_df):
 
         Parameters
         ----------
-        weather_df : pandas.DataFrame
+        weather_df : :pandas:`pandas.DataFrame<frame>`
             DataFrame with time series for wind speed `wind_speed` in m/s, and
             roughness length `roughness_length` in m, as well as optionally
             temperature `temperature` in K, pressure `pressure` in Pa and
@@ -382,16 +382,9 @@ def run_model(self, weather_df):
             measured at a height of 10 m). See below for an example on how to
             create the weather_df DataFrame.
 
-        Other Parameters
-        ----------------
-        roughness_length : Float, optional.
-            Roughness length.
-        turbulence_intensity : Float, optional.
-            Turbulence intensity.
-
         Returns
         -------
-        self
+        :class:`~.modelchain.ModelChain`
 
         Examples
         ---------

diff --git a/windpowerlib/power_curves.py b/windpowerlib/power_curves.py
@@ -54,7 +54,7 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
 
     Returns
     -------
-    smoothed_power_curve_df : :pandas:`pandas.DataFrame<frame>`
+    :pandas:`pandas.DataFrame<frame>`
         Smoothed power curve. DataFrame has 'wind_speed' and 'value' columns
         with wind speeds in m/s and the corresponding power curve value in W.
 
@@ -180,21 +180,21 @@ def wake_losses_to_power_curve(power_curve_wind_speeds, power_curve_values,
 
     Parameters
     ----------
-    power_curve_wind_speeds : pandas.Series or numpy.array
+    power_curve_wind_speeds : :pandas:`pandas.Series<series>` or numpy.array
         Wind speeds in m/s for which the power curve values are provided in
         `power_curve_values`.
-    power_curve_values : pandas.Series or numpy.array
+    power_curve_values : :pandas:`pandas.Series<series>` or numpy.array
         Power curve values corresponding to wind speeds in
         `power_curve_wind_speeds`.
-    wind_farm_efficiency : float or pd.DataFrame
+    wind_farm_efficiency : float or :pandas:`pandas.DataFrame<frame>`
         Efficiency of the wind farm. Either constant (float) or efficiency
         curve (pd.DataFrame) containing 'wind_speed' and 'efficiency' columns
         with wind speeds in m/s and the corresponding dimensionless wind farm
         efficiency (reduction of power). Default: None.
 
     Returns
     -------
-    power_curve_df : pd.DataFrame
+    :pandas:`pandas.DataFrame<frame>`
         Power curve with power values reduced by a wind farm efficiency.
         DataFrame has 'wind_speed' and 'value' columns with wind speeds in m/s
         and the corresponding power curve value in W.

diff --git a/windpowerlib/power_output.py b/windpowerlib/power_output.py
@@ -23,29 +23,29 @@ def power_coefficient_curve(wind_speed, power_coefficient_curve_wind_speeds,
 
     Parameters
     ----------
-    wind_speed : pandas.Series or numpy.array
+    wind_speed : :pandas:`pandas.Series<series>` or numpy.array
         Wind speed at hub height in m/s.
-    power_coefficient_curve_wind_speeds : pandas.Series or numpy.array
+    power_coefficient_curve_wind_speeds : :pandas:`pandas.Series<series>` or numpy.array
         Wind speeds in m/s for which the power coefficients are provided in
         `power_coefficient_curve_values`.
-    power_coefficient_curve_values : pandas.Series or numpy.array
+    power_coefficient_curve_values : :pandas:`pandas.Series<series>` or numpy.array
         Power coefficients corresponding to wind speeds in
         `power_coefficient_curve_wind_speeds`.
     rotor_diameter : float
         Rotor diameter in m.
-    density : pandas.Series or numpy.array
+    density : :pandas:`pandas.Series<series>` or numpy.array
         Density of air at hub height in kg/m³.
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Electrical power output of the wind turbine in W.
         Data type depends on type of `wind_speed`.
 
     Notes
     -----
     The following equation is used if the parameter `density_corr` is False
-    [1]_, [2]_:
+    [1]_ [2]_:
 
     .. math:: P=\frac{1}{8}\cdot\rho_{hub}\cdot d_{rotor}^{2}
         \cdot\pi\cdot v_{wind}^{3}\cdot cp\left(v_{wind}\right)
@@ -93,25 +93,25 @@ def power_curve(wind_speed, power_curve_wind_speeds, power_curve_values,
 
     Parameters
     ----------
-    wind_speed : pandas.Series or numpy.array
+    wind_speed : :pandas:`pandas.Series<series>` or numpy.array
         Wind speed at hub height in m/s.
-    power_curve_wind_speeds : pandas.Series or numpy.array
+    power_curve_wind_speeds : :pandas:`pandas.Series<series>` or numpy.array
         Wind speeds in m/s for which the power curve values are provided in
         `power_curve_values`.
     power_curve_values : pandas.Series or numpy.array
         Power curve values corresponding to wind speeds in
         `power_curve_wind_speeds`.
-    density : pandas.Series or numpy.array
+    density : :pandas:`pandas.Series<series>` or numpy.array
         Density of air at hub height in kg/m³. This parameter is needed
         if `density_correction` is True. Default: None.
-    density_correction : boolean
+    density_correction : bool
         If the parameter is True the density corrected power curve is used for
         the calculation of the turbine power output. In this case `density`
         cannot be None. Default: False.
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Electrical power output of the wind turbine in W.
         Data type depends on type of `wind_speed`.
 
@@ -150,27 +150,27 @@ def power_curve_density_correction(wind_speed, power_curve_wind_speeds,
 
     Parameters
     ----------
-    wind_speed : pandas.Series or numpy.array
+    wind_speed : :pandas:`pandas.Series<series>` or numpy.array
         Wind speed at hub height in m/s.
-    power_curve_wind_speeds : pandas.Series or numpy.array
+    power_curve_wind_speeds : :pandas:`pandas.Series<series>` or numpy.array
         Wind speeds in m/s for which the power curve values are provided in
         `power_curve_values`.
-    power_curve_values : pandas.Series or numpy.array
+    power_curve_values : :pandas:`pandas.Series<series>` or numpy.array
         Power curve values corresponding to wind speeds in
         `power_curve_wind_speeds`.
-    density : pandas.Series or numpy.array
+    density : :pandas:`pandas.Series<series>` or numpy.array
         Density of air at hub height in kg/m³.
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Electrical power output of the wind turbine in W.
         Data type depends on type of `wind_speed`.
 
     Notes
     -----
     The following equation is used for the site specific power curve wind
-    speeds [1]_, [2]_, [3]_:
+    speeds [1]_ [2]_ [3]_:
 
     .. math:: v_{site}=v_{std}\cdot\left(\frac{\rho_0}
                        {\rho_{site}}\right)^{p(v)}

diff --git a/windpowerlib/temperature.py b/windpowerlib/temperature.py
@@ -19,7 +19,7 @@ def linear_gradient(temperature, temperature_height, hub_height):
 
     Parameters
     ----------
-    temperature : pandas.Series or numpy.array
+    temperature : :pandas:`pandas.Series<series>` or numpy.array
         Air temperature in K.
     temperature_height : float
         Height in m for which the parameter `temperature` applies.
@@ -28,7 +28,7 @@ def linear_gradient(temperature, temperature_height, hub_height):
 
     Returns
     -------
-    pandas.Series or numpy.array
+    :pandas:`pandas.Series<series>` or numpy.array
         Temperature at hub height in K.
 
     Notes