Merge pull request #22 from wholmgren/docfixes

0.1 documentation improvements

Author: robwandrews

docs/sphinx/source/comparison_pvlib_matlab.rst

@@ -0,0 +1,64 @@
+.. _comparison_pvlib_matlab:
+
+****************************
+Comparison with PVLIB_MATLAB
+****************************
+
+This document is under construction.
+Please see our 
+`PVSC 2014 paper <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_
+and
+`PVSC 2015 abstract <https://github.com/UARENForecasting/pvlib-pvsc2015/blob/master/pvlib_pvsc_42.pdf?raw=true>`_ 
+for more information.
+
+The pvlib-python license is BSD 3-clause,
+the PVLIB\_MATLAB license is ??.
+
+We want to keep developing the core functionality and algorithms 
+of the Python and MATLAB projects roughly in parallel, 
+but we're not making any promises at this point.
+The PVLIB\_MATLAB and pvlib-python projects are currently developed 
+by different teams that do not regularly work together. 
+We hope to grow this collaboration in the future.
+Do not expect feature parity between the libaries, only similarity.
+
+Here are some of the major differences between the latest pvlib-python build 
+and the original Sandia PVLIB\_Python project, but many of these
+comments apply to the difference between pvlib-python and PVLIB\_MATLAB.
+
+
+Library wide changes
+~~~~~~~~~~~~~~~~~~~~
+
+* Remove ``pvl_`` from module names.
+* Consolidation of similar modules. For example, functions from ``pvl_clearsky_ineichen.py`` and ``pvl_clearsky_haurwitz.py`` have been consolidated into ``clearsky.py``. 
+* Removed ``Vars=Locals(); Expect...; var=pvl\_tools.Parse(Vars,Expect);`` pattern. Very few tests of input validitity remain. Garbage in, garbage or ``nan`` out.
+* Removing unnecssary and sometimes undesired behavior such as setting maximum zenith=90 or airmass=0. Instead, we make extensive use of ``nan`` values.
+* Changing function and module names so that they do not conflict.
+* Added ``/pvlib/data`` for lookup tables, test, and tutorial data.
+
+
+More specific changes
+~~~~~~~~~~~~~~~~~~~~~
+
+* Add PyEphem option to solar position calculations. 
+* ``irradiance.py`` has more AOI, projection, and irradiance sum and calculation functions
+* Locations are now ``pvlib.location.Location`` objects, not structs.
+* Specify time zones using a string from the standard IANA Time Zone Database naming conventions or using a pytz.timezone instead of an integer GMT offset. We may add dateutils support in the future.
+* ``clearsky.ineichen`` supports interpolating monthly Linke Turbidities to daily resolution.
+
+Documentation
+~~~~~~~~~~~~~
+
+* Using readthedocs for documentation hosting.
+* Many typos and formatting errors corrected.
+* Documentation source code and tutorials live in ``/`` rather than ``/pvlib/docs``.
+* Additional tutorials in ``/docs/tutorials``.
+
+Testing
+~~~~~~~
+
+* Tests are cleaner and more thorough. They are still no where near complete.
+* Using Coveralls to measure test coverage. 
+* Using TravisCI for automated testing.
+* Using ``nosetests`` for more concise test code. 

docs/sphinx/source/conf.py

@@ -47,6 +47,7 @@ def __getattr__(cls, name):
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.extlinks',
     'numpydoc',
     'sphinx.ext.autosummary'
 ]
@@ -64,8 +65,8 @@ def __getattr__(cls, name):
 master_doc = 'index'
 
 # General information about the project.
-project = u'PVLIB_Python'
-copyright = u'2014, Sandia National Labs, Rob Andrews, University of Arizona, github contributors'
+project = u'pvlib-python'
+copyright = u'2015, Sandia National Labs, Rob Andrews, University of Arizona, github contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -191,7 +192,7 @@ def __getattr__(cls, name):
 #html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -246,6 +247,11 @@ def __getattr__(cls, name):
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+# extlinks alias
+extlinks = {'issue': ('https://github.com/pvlib/pvlib-python/issues/%s',
+                      'GH'),
+            'wiki': ('https://github.com/pvlib/pvlib-python/wiki/%s',
+                     'wiki ')}
 
 # -- Options for manual page output ---------------------------------------
 

docs/sphinx/source/index.rst

@@ -1,25 +1,60 @@
-.. PVLIB_Python documentation master file, created by
-   sphinx-quickstart on Fri Nov  7 15:56:33 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to pvlib/pvlib-python's documentation!
+Welcome to pvlib-python's documentation!
 ========================================
 
-This is the documentation for the pvlib-python project hosted at
-https://github.com/pvlib/pvlib-python
+pvlib-python provides a set of documented functions for simulating 
+the performance of photovoltaic energy systems. 
+The toolbox was originally developed in MATLAB 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/.
+
+The source code for pvlib-python is hosted on 
+`github <https://github.com/pvlib/pvlib-python>`_.
+
+The github page also contains a valuable
+`wiki <https://github.com/pvlib/pvlib-python/wiki>`_
+with information on how you can contribute to pvlib-python development!
+
+Please see the links above for details on the status of the pvlib-python
+project. We are at an early stage in the development of this project,
+so expect to see significant API changes in the next few releases.
+
+This documenation focuses on providing a reference for all of 
+the modules and functions available in pvlib-python.
+For examples of how to use pvlib-python, please see the
+`tutorials <http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/>`_.
+
+.. note::
+
+   This documentation assumes general familiarity with
+   Python, NumPy, and Pandas. Google searches will yield many
+   excellent tutorials for these packages. 
+   
+Please see our 
+`PVSC 2014 paper <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_
+and
+`PVSC 2015 abstract <https://github.com/UARENForecasting/pvlib-pvsc2015/blob/master/pvlib_pvsc_42.pdf?raw=true>`_ 
+for more information.
 
-You may also want to browser the tutorials using nbviewer at 
-http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/
+Installation
+============
 
+1. Follow Pandas' 
+   `instructions <http://pandas.pydata.org/pandas-docs/stable/install.html>`_
+   for installing the scientific python stack, including ``pip``.
+#. ``pip install pvlib-python``
 
 
-Contents:
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
    self
+   whatsnew
+   comparison_pvlib_matlab
    pvlib
 
 

docs/sphinx/source/whatsnew.rst

@@ -0,0 +1,9 @@
+.. _whatsnew:
+
+**********
+What's New
+**********
+
+These are new features and improvements of note in each release.
+
+.. include:: whatsnew/v0.1.0.txt

docs/sphinx/source/whatsnew/v0.1.0.txt

@@ -0,0 +1,90 @@
+.. _whatsnew_0100:
+
+v0.1.0 (March 17, 2015)
+-----------------------
+
+This is the first official release of the pvlib-python project.
+As such, a "What's new" document is a little hard to write.
+There will be significant overlap with the to-be-written document
+that describes the differences between pvlib-python and PVLIB\_Matlab.
+
+
+API changes
+~~~~~~~~~~~
+
+* Remove ``pvl_`` from module names.
+* Consolidation of similar modules. For example, functions from ``pvl_clearsky_ineichen.py`` and ``pvl_clearsky_haurwitz.py`` have been consolidated into ``clearsky.py``. 
+* Return one DataFrame instead of a tuple of DataFrames.
+* Change function and module names so that they do not conflict.
+
+
+New features
+~~~~~~~~~~~~
+
+* Library is Python 3.3 and 3.4 compatible
+* Add What's New section to docs (:issue:`10`)
+* Add PyEphem option to solar position calculations. 
+* ``irradiance.py`` has more AOI, projection, and irradiance sum and calculation functions
+* TMY data import has a ``coerce_year`` option
+* TMY data can be loaded from a url (:issue:`5`)
+* Locations are now ``pvlib.location.Location`` objects, not "structs".
+* Specify time zones using a string from the standard IANA Time Zone Database naming conventions or using a pytz.timezone instead of an integer GMT offset. We may add dateutils support in the future.
+* ``clearsky.ineichen`` supports interpolating monthly Linke Turbidities to daily resolution.
+
+
+Other changes
+~~~~~~~~~~~~~
+
+* Removed ``Vars=Locals(); Expect...; var=pvl\_tools.Parse(Vars,Expect);`` pattern. Very few tests of input validitity remain. Garbage in, garbage or ``nan`` out.
+* Removing unnecssary and sometimes undesired behavior such as setting maximum zenith=90 or airmass=0. Instead, we make extensive use of ``nan`` values.
+* Adding logging calls, removing print calls.
+* Improved PEP8 compliance.
+* Added ``/pvlib/data`` for lookup tables, test, and tutorial data.
+
+
+Documentation
+~~~~~~~~~~~~~
+
+* Using readthedocs for documentation hosting.
+* Many typos and formatting errors corrected (:issue:`16`)
+* Documentation source code and tutorials live in ``/`` rather than ``/pvlib/docs``.
+* Additional tutorials in ``/docs/tutorials``.
+* Clarify ``pvsystem.systemdef`` input (:issue:`17`)
+
+
+Testing
+~~~~~~~
+
+* Tests are cleaner and more thorough. They are still no where near complete.
+* Using Coveralls to measure test coverage. 
+* Using TravisCI for automated testing.
+* Using ``nosetests`` for more concise test code. 
+
+
+Bug fixes
+~~~~~~~~~
+
+* Fixed DISC algorithm bugs concerning 
+  modifying input zenith Series (:issue:`24`),
+  the ``Kt`` conditional evaluation (:issue:`6`),
+  and ignoring the input pressure (:issue:`25`).
+* Many more bug fixes were made, but you'll have to look at the detailed commit history.
+
+
+Contributors
+~~~~~~~~~~~~
+
+This list includes all (I hope) contributors to 
+`pvlib/pvlib-python <https://github.com/pvlib/pvlib-python>`_,
+`Sandia-Labs/PVLIB_Python <https://github.com/Sandia-Labs/PVLIB_Python>`_,
+and
+`UARENForecasting/PVLIB_Python <https://github.com/UARENForecasting/PVLIB_Python>`_.
+
+* Rob Andrews
+* Will Holmgren
+* bmu
+* Tony Lorenzo
+* jforbess
+* Jorissup
+* dacoex
+* alexisph

pvlib/atmosphere.py

@@ -1,5 +1,5 @@
 """
-The atmosphere module contains methods to calculate 
+The ``atmosphere`` module contains methods to calculate 
 relative and absolute airmass and to determine
 pressure from altitude or vice versa.
 """
@@ -18,7 +18,7 @@
 
 def pres2alt(pressure):
     '''
-    Determine altitude from site pressure
+    Determine altitude from site pressure.
 
     Parameters
     ----------
@@ -42,7 +42,7 @@ def pres2alt(pressure):
     Gravitational acceleration     9.80665 m/s^2
     Lapse rate                     -6.5E-3 K/m
     Gas constant for air           287.053 J/(kgK)
-    Relative Humidity               0%
+    Relative Humidity              0%
     ============================   ================
 
     References
@@ -60,7 +60,7 @@ def pres2alt(pressure):
 
 def alt2pres(altitude):
     '''
-    Determine site pressure from altitude
+    Determine site pressure from altitude.
 
     Parameters
     ----------
@@ -84,7 +84,7 @@ def alt2pres(altitude):
     Gravitational acceleration     9.80665 m/s^2
     Lapse rate                     -6.5E-3 K/m
     Gas constant for air           287.053 J/(kgK)
-    Relative Humidity               0%
+    Relative Humidity              0%
     ============================   ================
 
     References
@@ -130,15 +130,10 @@ def absoluteairmass(AMrelative, pressure=101325.):
 
     References
     ----------
-
     [1] C. Gueymard, "Critical analysis and performance assessment of 
     clear sky solar irradiance models using theoretical and measured data,"
     Solar Energy, vol. 51, pp. 121-138, 1993.
 
-    See also 
-    ---------
-    relativeairmass 
-
     '''
 
     AMa = AMrelative * pressure / 101325.