Merge branch 'features/revise_example' into features/improve_documentation

Conflicts:
	example/basic_example.ipynb

Author: Birgit Schachler

doc/example.rst

@@ -0,0 +1,10 @@
+.. currentmodule:: example
+
+.. autosummary::
+   :toctree: temp/
+
+   basic_example.get_weather_data
+   basic_example.initialise_wind_turbines
+   basic_example.calculate_power_output
+   basic_example.plot_or_print
+   basic_example.run_basic_example

doc/modules.rst

@@ -93,4 +93,12 @@ Methods of the ModelChain object.
 
    modelchain.ModelChain.rho_hub
    modelchain.ModelChain.v_wind_hub
-   modelchain.ModelChain.turbine_power_output
+   modelchain.ModelChain.turbine_power_output
+
+
+Example
+==============
+
+The basic example consists of the following functions.
+
+.. include:: example.rst

example/basic_example.ipynb

@@ -9,7 +9,14 @@
     "This example shows you the basic usage of the windpowerlib. \n",
     "There are mainly three steps. First you have to import your weather data, then you need to specify your wind turbine, and in the last step call the windpowerlib functions to calculate the feedin timeseries.\n",
     "\n",
-    "But first of all you need to import the packages needed for the different steps."
+    "Before you start you have to import the packages needed for these steps."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import necessary packages and modules"
    ]
   },
   {
@@ -163,9 +170,10 @@
     "wt.get_turbine_types(print_out=False)\n",
     "\n",
     "# get power coefficient curves\n",
-    "# write names of wind turbines for which power coefficient curves are provided to 'turbines' DataFrame\n",
+    "# write names of wind turbines for which power coefficient curves are provided\n",
+    "# to 'turbines' DataFrame\n",
     "turbines = wt.get_turbine_types(filename='cp_curves.csv', print_out=False)\n",
-    "# find all Vestas in 'turbines' DataFrame\n",
+    "# find all Enercons in 'turbines' DataFrame\n",
     "print(turbines[turbines[\"turbine_id\"].str.contains(\"ENERCON\")])"
    ]
   },
@@ -177,14 +185,16 @@
    },
    "outputs": [],
    "source": [
-    "# specification of own wind turbine (Note: power coefficient values and nominal power have to be in Watt)\n",
+    "# specification of own wind turbine (Note: power coefficient values and\n",
+    "# nominal power have to be in Watt)\n",
     "myTurbine = {\n",
     "    'turbine_name': 'myTurbine',\n",
     "    'nominal_power': 3e6,  # in W\n",
     "    'hub_height': 105,  # in m\n",
     "    'd_rotor': 90,  # in m\n",
     "    'p_values': pd.DataFrame(\n",
-    "        data={'p': [p * 1000 for p in [0.0, 26.0, 180.0, 1500.0, 3000.0, 3000.0]]},  # in W\n",
+    "        data={'p': [p * 1000 for p in\n",
+    "                    [0.0, 26.0, 180.0, 1500.0, 3000.0, 3000.0]]},  # in W\n",
     "        index=[0.0, 3.0, 5.0, 10.0, 15.0, 25.0])  # in m/s\n",
     "    }  \n",
     "# initialise WindTurbine object\n",
@@ -200,7 +210,8 @@
    "outputs": [],
    "source": [
     "# specification of wind turbine where power curve is provided\n",
-    "# if you want to use the power coefficient curve add {'fetch_curve': 'cp'} to the dictionary\n",
+    "# if you want to use the power coefficient curve add {'fetch_curve': 'cp'}\n",
+    "# to the dictionary\n",
     "enerconE126 = {\n",
     "    'turbine_name': 'ENERCON E 126 7500',  # turbine name as in register\n",
     "    'hub_height': 135,  # in m\n",
@@ -226,7 +237,8 @@
    "outputs": [],
    "source": [
     "# power output calculation for my_turbine\n",
-    "# initialise ModelChain with default parameters and use run_model method to calculate power output\n",
+    "# initialise ModelChain with default parameters and use run_model\n",
+    "# method to calculate power output\n",
     "mc_my_turbine = modelchain.ModelChain(my_turbine).run_model(\n",
     "    weather, data_height)\n",
     "# write power output timeseries to WindTurbine object\n",
@@ -248,7 +260,8 @@
     "    'power_output_model': 'p_values',  # 'p_values' (default) or 'cp_values'\n",
     "    'density_corr': True,              # False (default) or True\n",
     "    'hellman_exp': None}               # None (default) or None\n",
-    "# initialise ModelChain with own specifications and use run_model method to calculate power output\n",
+    "# initialise ModelChain with own specifications and use run_model method to\n",
+    "# calculate power output\n",
     "mc_e126 = modelchain.ModelChain(e126, **modelchain_data).run_model(\n",
     "    weather, data_height)\n",
     "# write power output timeseries to WindTurbine object\n",

example/basic_example.py

@@ -104,19 +104,18 @@ def read_weather_data(filename, datetime_column='time_index',
     return (weather, data_height)
 
 
-# TODO markdown for code snippet
 def initialise_wind_turbines():
     r"""
     Initialises two :class:`~.wind_turbine.WindTurbine` objects.
 
     Function shows two ways to initialise a WindTurbine object. You can either
     specify your own turbine, as done below for 'myTurbine', or fetch power
     and/or power coefficient curve data from data files provided by the
-    windpowerlib, as done for the 'enerconE126'. Execute
-    windpowerlib.wind_turbine.get_turbine_types() or
-    windpowerlib.wind_turbine.get_turbine_types(filename='cp_curves.csv')
-    to get a list of all wind turbines for which power or power coefficient
-    curves, respectively, are provided.
+    windpowerlib, as done for the 'enerconE126'.
+    Execute ``windpowerlib.wind_turbine.get_turbine_types()`` or
+    ``windpowerlib.wind_turbine.get_turbine_types(filename='cp_curves.csv')``
+    to get a list of all wind turbines for which power and power coefficient
+    curves respectively are provided.
 
     Returns
     -------
@@ -251,6 +250,10 @@ def plot_or_print(my_turbine, e126):
 
 
 def run_basic_example():
+    r"""
+    Run the basic example.
+
+    """
     weather, data_height = get_weather_data('weather.csv')
     my_turbine, e126 = initialise_wind_turbines()
     calculate_power_output(weather, data_height, my_turbine, e126)