Add logos and clarify some docstrings

README.md

@@ -1,5 +1,4 @@
-pvlib-python
-============
+<img src="docs/sphinx/source/_images/pvlib_logo_horiz.png" width="600" height="260">
 
 [![TravisCI](https://travis-ci.org/pvlib/pvlib-python.svg?branch=master)](https://travis-ci.org/pvlib/pvlib-python)
 [![Build status](https://ci.appveyor.com/api/projects/status/gr2eyhc84tvtkopk?svg=true)](https://ci.appveyor.com/project/wholmgren/pvlib-python-fv2to)
@@ -13,9 +12,9 @@ pvlib-python
 [![Total Alerts](https://img.shields.io/lgtm/alerts/g/pvlib/pvlib-python.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/pvlib/pvlib-python/alerts)
 
 
-PVLIB Python is a community supported tool that provides a set of
+pvlib python is a community supported tool that provides a set of
 functions and classes for simulating the performance of photovoltaic
-energy systems. PVLIB Python was originally ported from the PVLIB MATLAB
+energy systems. pvlib python was originally ported from the PVLIB MATLAB
 toolbox developed at Sandia National Laboratories and it implements many
 of the models and methods developed at the Labs. More information on
 Sandia Labs PV performance modeling programs can be found at

docs/sphinx/source/index.rst

@@ -1,28 +1,30 @@
-pvlib-python
+.. image:: _images/pvlib_logo_horiz.png
+  :width: 600
+
 ========================================
 
-PVLIB Python is a community supported tool that provides a set of
+pvlib python is a community supported tool that provides a set of
 functions and classes for simulating the performance of photovoltaic
-energy systems. PVLIB Python was originally ported from the PVLIB MATLAB
+energy systems. pvlib python was originally ported from the PVLIB MATLAB
 toolbox developed at Sandia National Laboratories and it implements many
 of the models and methods developed at the Labs. More information on
 Sandia Labs PV performance modeling programs can be found at
 https://pvpmc.sandia.gov/. We collaborate with the PVLIB MATLAB project,
 but operate independently of it.
 
-The source code for pvlib-python is hosted on `github
+The source code for pvlib python is hosted on `github
 <https://github.com/pvlib/pvlib-python>`_.
 
 Please see the :ref:`installation` page for installation help.
 
-For examples of how to use pvlib-python, please see
+For examples of how to use pvlib python, please see
 :ref:`package_overview` and our `Jupyter Notebook tutorials
 <http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/
 tutorials/>`_. The documentation assumes general familiarity with
 Python, NumPy, and Pandas. Google searches will yield many
 excellent tutorials for these packages.
 
-The pvlib-python GitHub wiki has a `Projects and publications that use
+The pvlib python GitHub wiki has a `Projects and publications that use
 pvlib python
 <https://github.com/pvlib/pvlib-python/wiki/Projects-and-publications-
 that-use-pvlib-python>`_ page for inspiration and listing of your
@@ -31,23 +33,23 @@ application.
 There is a :ref:`variable naming convention <variables_style_rules>` to
 ensure consistency throughout the library.
 
-Citing pvlib-python
+Citing pvlib python
 ===================
 
 Many of the contributors to pvlib-python work in institutions where
 citation metrics are used in performance or career evaluations. If you
-use pvlib-python in a published work, please cite:
+use pvlib python in a published work, please cite:
 
   William F. Holmgren, Clifford W. Hansen, and Mark A. Mikofski.
   "pvlib python: a python package for modeling solar energy systems."
   Journal of Open Source Software, 3(29), 884, (2018).
   https://doi.org/10.21105/joss.00884
 
 Please also cite the DOI corresponding to the specific version of
-pvlib-python that you used. pvlib-python DOIs are listed at
+pvlib python that you used. pvlib python DOIs are listed at
 `Zenodo.org <https://zenodo.org/search?page=1&size=20&q=conceptrecid:593284&all_versions&sort=-version>`_
 
-Additional pvlib-python publications include:
+Additional pvlib python publications include:
 
 * J. S. Stein, “The photovoltaic performance modeling
   collaborative (PVPMC),” in Photovoltaic Specialists Conference, 2012.

pvlib/clearsky.py

@@ -327,7 +327,7 @@ def _linearly_scale(inputmatrix, inputmin, inputmax, outputmin, outputmax):
 
 def haurwitz(apparent_zenith):
     '''
-    Determine clear sky GHI from Haurwitz model.
+    Determine clear sky GHI using the Haurwitz model.
 
     Implements the Haurwitz clear sky model for global horizontal
     irradiance (GHI) as presented in [1, 2]. A report on clear
@@ -343,11 +343,9 @@ def haurwitz(apparent_zenith):
 
     Returns
     -------
-    pd.DataFrame
-    The modeled global horizonal irradiance in W/m^2 provided
-    by the Haurwitz clear-sky model.
-
-    Initial implementation of this algorithm by Matthew Reno.
+    ghi : DataFrame
+        The modeled global horizonal irradiance in W/m^2 provided
+        by the Haurwitz clear-sky model.
 
     References
     ----------

pvlib/irradiance.py

@@ -447,11 +447,10 @@ def get_sky_diffuse(surface_tilt, surface_azimuth,
 
 def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse):
     r'''
-    Determine the three components on in-plane irradiance
+    Determine in-plane irradiance components.
 
-    Combines in-plane irradaince compoents from the chosen diffuse
-    translation, ground reflection and beam irradiance algorithms into
-    the total in-plane irradiance.
+    Combines DNI with sky diffuse and ground-reflected irradiance to calculate
+    total, direct and diffuse irradiance components in the plane of array.
 
     Parameters
     ----------