Merge pull request #25 from wind-python/release_preparation

Release preparation: Changes to documentation, Renaming of examples, Fixes, Elimination of Warnings...

Author: SabineHaas

.gitignore

@@ -36,6 +36,8 @@ pip-delete-this-directory.txt
 
 # Doc
 doc/temp/
+.doctrees
+.buildinfo
 
 # Unit test / coverage reports
 htmlcov/

README.rst

@@ -7,7 +7,7 @@ Introduction
 =============
 
 The windpowerlib is a library that provides a set of functions and classes to calculate the power output of wind turbines. It was originally part of the 
-`feedinlib <https://github.com/oemof/feedinlib>`_ (windpower and pv) but was taken out to build up a community concentrating on wind power models.
+`feedinlib <https://github.com/oemof/feedinlib>`_ (windpower and photovoltaic) but was taken out to build up a community concentrating on wind power models.
 
 For a quick start see the `Examples and basic usage <http://windpowerlib.readthedocs.io/en/stable/getting_started.html#examplereference-label>`_ section.
 
@@ -45,33 +45,61 @@ Matplotlib can be installed using pip3 though some Linux users reported that it
 Examples and basic usage
 =========================
 
-The basic usage of the windpowerlib is shown `here <http://windpowerlib.readthedocs.io/en/stable/basic_example_notebook.html>`_. The presented example is available as jupyter notebook and python script. You can download them along with example weather data:
+The basic usage of the windpowerlib is shown in the `modelchain_example <http://windpowerlib.readthedocs.io/en/stable/basic_example_notebook.html>`_. The presented example is available as jupyter notebook and python script. You can download them along with example weather data:
 
- * `Basic example (Python script) <https://raw.githubusercontent.com/wind-python/windpowerlib/master/example/basic_example.py>`_
- * `Basic example (Jupyter notebook) <https://raw.githubusercontent.com/wind-python/windpowerlib/features/revise_example/example/basic_example.ipynb>`_
+ * `ModelChain example (Python script) <https://raw.githubusercontent.com/wind-python/windpowerlib/master/example/basic_example.py>`_
+ * `ModelChain example (Jupyter notebook) <https://raw.githubusercontent.com/wind-python/windpowerlib/features/revise_example/example/basic_example.ipynb>`_
  * `Example data file <https://raw.githubusercontent.com/wind-python/windpowerlib/master/example/weather.csv>`_
 
 
 To run the examples you first have to install the windpowerlib. To run the notebook you also need to install notebook using pip3. To launch jupyter notebook type ``jupyter notebook`` in terminal.
 This will open a browser window. Navigate to the directory containing the notebook to open it. See the jupyter notebook quick start guide for more information on `how to install <http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/install.html>`_ and
 `how to run <http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/execute.html>`_ jupyter notebooks.
 
-The usage of further functions are shown in a second example. As the basic usage example it is available as jupyter notebook and as python script. The weather data in this example is the same as in the example above.
+Further functionalities, like the modelling of wind farms and wind turbine clusters, are shown in a second example. As the ModelChain example it is available as jupyter notebook and as python script. The weather data in this example is the same as in the example above.
 
- * `Further example (Python script) <https://raw.githubusercontent.com/wind-python/windpowerlib/release_preparation/example/further_example.py>`_
- * `Further example (Jupyter notebook) <https://raw.githubusercontent.com/wind-python/windpowerlib/release_preparation/example/basic_example.ipynb>`_
+ * `TurbineClusterModelChain example (Python script) <https://raw.githubusercontent.com/wind-python/windpowerlib/release_preparation/example/further_example.py>`_
+ * `TurbineClusterModelChain example (Jupyter notebook) <https://raw.githubusercontent.com/wind-python/windpowerlib/release_preparation/example/basic_example.ipynb>`_
  * `Example data file <https://raw.githubusercontent.com/wind-python/windpowerlib/master/example/weather.csv>`_
 
 
 Contributing
 ==============
 
-Clone/Fork: https://github.com/wind-python/windpowerlib
+We are warmly welcoming all who want to contribute to the windpowerlib. If you are interested in wind models and want to help improving the existing model do not hesitate to contact us.
 
-If you are interested in wind models and want to help improve the existing model do not hesitate to contact us.
-As the windpowerlib started with contributors from the `oemof developer group <https://github.com/orgs/oemof/teams/oemof-developer-group>`_ we use the same 
+Clone: https://github.com/wind-python/windpowerlib and install the cloned repository using pip:
+
+.. code:: bash
+
+  pip install -e /path/to/the/repository
+
+As the windpowerlib started with contributors from the `oemof developer group <https://github.com/orgs/oemof/teams/oemof-developer-group>`_ we use the same
 `developer rules <http://oemof.readthedocs.io/en/stable/developing_oemof.html>`_.
 
+**How to create a pull request:**
+
+* `Fork <https://help.github.com/articles/fork-a-repo>`_ the windpowerlib repository to your own github account.
+* Change, add or remove code.
+* Commit your changes.
+* Create a `pull request <https://guides.github.com/activities/hello-world/>`_ and describe what you will do and why.
+* Wait for approval.
+
+**Generally the following steps are required when changing, adding or removing code:**
+
+* Add new tests if you have written new functions/classes.
+* Add/change the documentation (new feature, API changes ...).
+* Add a whatsnew entry and your name to Contributors.
+* Check if all tests still work by simply executing pytest in your windpowerlib directory:
+
+.. role:: bash(code)
+   :language: bash
+
+.. code:: bash
+
+    pytest
+
+
 Citing the windpowerlib
 ========================
 

doc/basic_example_notebook.ipynb

@@ -3,8 +3,8 @@
 .. 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
+   modelchain_example.get_weather_data
+   modelchain_example.initialize_wind_turbines
+   modelchain_example.calculate_power_output
+   modelchain_example.plot_or_print
+   modelchain_example.run_example

doc/example.rst

@@ -3,8 +3,8 @@
 .. autosummary::
    :toctree: temp/
 
-   further_example.initialise_wind_farm
-   further_example.initialise_wind_turbine_cluster
-   further_example.calculate_power_output
-   further_example.plot_or_print
-   further_example.run_example
+   turbine_cluster_modelchain_example.initialize_wind_farms
+   turbine_cluster_modelchain_example.initialize_wind_turbine_cluster
+   turbine_cluster_modelchain_example.calculate_power_output
+   turbine_cluster_modelchain_example.plot_or_print
+   turbine_cluster_modelchain_example.run_example

doc/example_2.rst

@@ -0,0 +1,9 @@
+#############
+Examples
+#############
+
+
+.. toctree::
+
+    modelchain_example_notebook
+    turbine_cluster_modelchain_example_notebook

doc/examples.rst

@@ -6,7 +6,7 @@ Introduction
 =============
 
 The windpowerlib is a library that provides a set of functions and classes to calculate the power output of wind turbines. It was originally part of the 
-`feedinlib <https://github.com/oemof/feedinlib>`_ (windpower and pv) but was taken out to build up a community concentrating on wind power models.
+`feedinlib <https://github.com/oemof/feedinlib>`_ (windpower and photovoltaic) but was taken out to build up a community concentrating on wind power models.
 
 For a quick start see the :ref:`examplereference-label` section.
 
@@ -44,31 +44,58 @@ Matplotlib can be installed using pip3 though some Linux users reported that it
 Examples and basic usage
 =========================
 
-The basic usage of the windpowerlib is shown :ref:`here <basic_example_notebook.ipynb>`. The presented example is available as jupyter notebook and python script. You can download them along with example weather data:
+The basic usage of the windpowerlib is shown in the :ref:`modelchain_example <modelchain_example_notebook.ipynb>`. The presented example is available as jupyter notebook and python script. You can download them along with example weather data:
 
- * :download:`Basic example (Python script) <../example/basic_example.py>`
- * :download:`Basic example (Jupyter notebook) <../example/basic_example.ipynb>`
+ * :download:`ModelChain example (Python script) <../example/modelchain_example.py>`
+ * :download:`ModelChain example (Jupyter notebook) <../example/modelchain_example.ipynb>`
  * :download:`Example data file <../example/weather.csv>`
 
 To run the examples you first have to install the windpowerlib. To run the notebook you also need to install notebook using pip3. To launch jupyter notebook type ``jupyter notebook`` in terminal.
 This will open a browser window. Navigate to the directory containing the notebook to open it. See the jupyter notebook quick start guide for more information on `how to install <http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/install.html>`_ and
 `how to run <http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/execute.html>`_ jupyter notebooks.
 
-Further functionalities are shown in a second example. As the basic usage example it is available as jupyter notebook and as python script. The weather data in this example is the same as in the example above.
+Further functionalities, like the modelling of wind farms and wind turbine clusters, are shown in a second example. As the ModelChain example it is available as jupyter notebook and as python script. The weather data in this example is the same as in the example above.
 
- * :download:`Further example (Python script) <../example/further_example.py>`
- * :download:`Further example (Jupyter notebook) <../example/further_example.ipynb>`
+ * :download:`TurbineClusterModelChain example (Python script) <../example/turbine_cluster_modelchain_example.py>`
+ * :download:`TurbineClusterModelChain example (Jupyter notebook) <../example/turbine_cluster_modelchain_example.ipynb>`
  * :download:`Example data file <../example/weather.csv>`
 
 Contributing
 ==============
 
-Clone/Fork: https://github.com/wind-python/windpowerlib
+We are warmly welcoming all who want to contribute to the windpowerlib. If you are interested in wind models and want to help improving the existing model do not hesitate to contact us.
 
-If you are interested in wind models and want to help improve the existing model do not hesitate to contact us.
-As the windpowerlib started with contributors from the `oemof developer group <https://github.com/orgs/oemof/teams/oemof-developer-group>`_ we use the same 
+Clone: https://github.com/wind-python/windpowerlib and install the cloned repository using pip:
+
+.. code:: bash
+
+  pip install -e /path/to/the/repository
+
+As the windpowerlib started with contributors from the `oemof developer group <https://github.com/orgs/oemof/teams/oemof-developer-group>`_ we use the same
 `developer rules <http://oemof.readthedocs.io/en/stable/developing_oemof.html>`_.
 
+**How to create a pull request:**
+
+* `Fork <https://help.github.com/articles/fork-a-repo>`_ the windpowerlib repository to your own github account.
+* Change, add or remove code.
+* Commit your changes.
+* Create a `pull request <https://guides.github.com/activities/hello-world/>`_ and describe what you will do and why.
+* Wait for approval.
+
+**Generally the following steps are required when changing, adding or removing code:**
+
+* Add new tests if you have written new functions/classes.
+* Add/change the documentation (new feature, API changes ...).
+* Add a whatsnew entry and your name to Contributors.
+* Check if all tests still work by simply executing pytest in your windpowerlib directory:
+
+.. role:: bash(code)
+   :language: bash
+
+.. code:: bash
+
+    pytest
+
 Citing the windpowerlib
 ========================
 

doc/examples_basic_and_further.rst

@@ -8,17 +8,7 @@ Contents:
    :glob:   
 
    getting_started
-
-.. toctree::
-   :maxdepth: 3
-   :glob:
-
-   examples_basic_and_further
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
+   examples
    whats_new
    modules