minor documentation updates (#312)

* update python, ipython, matplotlib, sphinx

* add notes about recommended solarposition methods

* fix long table of contents on front page

* mention marks new atmosphere functions in clearsky.rst

* add notes about stackoverflow and google groups

Author: wholmgren

docs/environment.yml

@@ -3,22 +3,22 @@ channels:
     - conda-forge
     - defaults
 dependencies:
-    - python=2.7
+    - python=3.5
     - mock  # needed for local python 2.7 builds
     - numpy=1.11.2
     - scipy
     - pandas=0.19.1
     - pytz
     - ephem
     - numba
-    - ipython=4.0.1
+    - ipython=5.2.2
     - ipywidgets
     - numpydoc
-    - matplotlib=1.5.3
+    - matplotlib=2.0.0
     - seaborn=0.7.1
     - siphon=0.4.0
-    - sphinx=1.4.8
-    - netCDF4=1.2.4
+    - sphinx=1.5
+    - netCDF4=1.2.5
     - hdf4=4.2.12
     - sphinx_rtd_theme
     - docutils

docs/sphinx/source/api.rst

@@ -31,6 +31,11 @@ Solar Position
 
 Functions and methods for calculating solar position.
 
+The :py:meth:`location.Location.get_solarposition` method and the
+:py:func:`solarposition.get_solarposition` function with default
+parameters are fast and accurate. We recommend using these functions
+unless you know that you need a different function.
+
 .. autosummary::
    :toctree: generated/
 

docs/sphinx/source/clearsky.rst

@@ -26,6 +26,10 @@ time series of clear sky data for a location. The :ref:`ineichen` and
 input data. The :ref:`detect_clearsky` subsection demonstrates the use
 of the clear sky detection algorithm.
 
+The :py:func:`~pvlib.atmosphere.bird_hulstrom80_aod_bb`, and
+:py:func:`~pvlib.atmosphere.kasten96_lt` functions are useful for
+calculating inputs to the clear sky functions.
+
 We'll need these imports for the examples below.
 
 .. ipython::
@@ -498,7 +502,6 @@ See [Ine16]_.
 We encourage users to compare the pvlib implementation to Ineichen's
 `Excel tool <http://www.unige.ch/energie/fr/equipe/ineichen/solis-tool/>`_.
 
-
 .. _detect_clearsky:
 
 Detect Clearsky

docs/sphinx/source/index.rst

@@ -68,7 +68,7 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 5
+   :maxdepth: 1
 
    package_overview
    whatsnew

docs/sphinx/source/package_overview.rst

@@ -272,7 +272,17 @@ community via issues and pull requests.
 
 Getting support
 ---------------
-The best way to get support is to make an issue on our
+
+pvlib usage questions can be asked on
+`Stack Overflow  <http://stackoverflow.com>`_ and tagged with
+the `pvlib <http://stackoverflow.com/questions/tagged/pvlib>`_ tag.
+
+The `pvlib-python google group <https://groups.google.com/forum/#!forum/pvlib-python>`_
+is used for discussing various topics of interest to the pvlib-python
+community. We also make new version announcements on the google group.
+
+If you suspect that you may have discovered a bug or if you'd like to
+change something about pvlib, then please make an issue on our
 `GitHub issues page <https://github.com/pvlib/pvlib-python/issues>`_ .
 
 

pvlib/solarposition.py

@@ -38,26 +38,33 @@ def get_solarposition(time, latitude, longitude,
     Parameters
     ----------
     time : pandas.DatetimeIndex
+
     latitude : float
+
     longitude : float
+
     altitude : None or float
         If None, computed from pressure. Assumed to be 0 m
         if pressure is also None.
+
     pressure : None or float
         If None, computed from altitude. Assumed to be 101325 Pa
         if altitude is also None.
-    method : string
-        'pyephem' uses the PyEphem package: :func:`pyephem`
-
-        'nrel_c' uses the NREL SPA C code [3]: :func:`spa_c`
 
+    method : string
         'nrel_numpy' uses an implementation of the NREL SPA algorithm
-        described in [1] (default): :func:`spa_python`
+        described in [1] (default, recommended): :py:func:`spa_python`
 
         'nrel_numba' uses an implementation of the NREL SPA algorithm
-        described in [1], but also compiles the code first: :func:`spa_python`
+        described in [1], but also compiles the code first:
+        :py:func:`spa_python`
+
+        'pyephem' uses the PyEphem package: :py:func:`pyephem`
+
+        'ephemeris' uses the pvlib ephemeris code: :py:func:`ephemeris`
+
+        'nrel_c' uses the NREL SPA C code [3]: :py:func:`spa_c`
 
-        'ephemeris' uses the pvlib ephemeris code: :func:`ephemeris`
     temperature : float
         Degrees C.
 
@@ -114,13 +121,15 @@ def spa_c(time, latitude, longitude, pressure=101325, altitude=0,
           raw_spa_output=False):
     """
     Calculate the solar position using the C implementation of the NREL
-    SPA code
+    SPA code.
 
     The source files for this code are located in './spa_c_files/', along with
     a README file which describes how the C code is wrapped in Python.
     Due to license restrictions, the C code must be downloaded seperately
     and used in accordance with it's license.
 
+    This function is slower and no more accurate than :py:func:`spa_python`.
+
     Parameters
     ----------
     time : pandas.DatetimeIndex
@@ -266,7 +275,7 @@ def spa_python(time, latitude, longitude,
         For most simulations specifing delta_t is sufficient.
         Difference between terrestrial time and UT1.
         *Note: delta_t = None will break code using nrel_numba,
-        this will be fixed in a future version.
+        this will be fixed in a future version.*
         The USNO has historical and forecasted delta_t [3].
     atmos_refrac : float, optional
         The approximate atmospheric refraction (in degrees)
@@ -807,7 +816,7 @@ def nrel_earthsun_distance(time, how='numpy', delta_t=67.0, numthreads=4):
         For most simulations specifing delta_t is sufficient.
         Difference between terrestrial time and UT1.
         *Note: delta_t = None will break code using nrel_numba,
-        this will be fixed in a future version.
+        this will be fixed in a future version.*
         By default, use USNO historical data and predictions
 
     numthreads : int, optional