reduce documentation build warnings (#210)

* pin doc env versions to rtd versions

* fix inline literal warning

* fix duplicate index warnings

* update whatsnew

Author: wholmgren

docs/environment.yml

@@ -1,14 +1,18 @@
-name: pvlib
+name: pvlibdocs
 dependencies:
     - python=2.7
+    - mock  # needed for local python 2.7 builds
     - numpy
     - scipy
     - pandas
     - pytz
     - ephem
     - numba
     - ipython=4.0.1
-    - sphinx
+    - ipywidgets
     - numpydoc
     - matplotlib
-    - seaborn
+    - seaborn
+    - sphinx=1.3.5  # same versions as rtd
+    - sphinx_rtd_theme=0.1.7
+    - docutils=0.12

docs/sphinx/source/classes.rst

@@ -17,39 +17,45 @@ Location
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 PVSystem
 --------
 .. autoclass:: pvlib.pvsystem.PVSystem
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 ModelChain
 ----------
 .. autoclass:: pvlib.modelchain.ModelChain
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 LocalizedPVSystem
 -----------------
 .. autoclass:: pvlib.pvsystem.LocalizedPVSystem
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 SingleAxisTracker
 -----------------
 .. autoclass:: pvlib.tracking.SingleAxisTracker
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 LocalizedSingleAxisTracker
 --------------------------
 .. autoclass:: pvlib.tracking.LocalizedSingleAxisTracker
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 

docs/sphinx/source/index.rst

@@ -46,11 +46,11 @@ of:
   modelling package,” in 40th IEEE Photovoltaic Specialist
   Conference, 2014.
   (`paper
-  <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_)
+  <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`__)
 * W.F. Holmgren, R.W. Andrews, A.T. Lorenzo, and J.S. Stein,
   “PVLIB Python 2015,” in 42nd Photovoltaic Specialists Conference, 2015.
   (`paper
-  <https://github.com/pvlib/pvsc2015/blob/master/pvlib_pvsc_42.pdf>`_ and
+  <https://github.com/pvlib/pvsc2015/blob/master/pvlib_pvsc_42.pdf>`__ and
   the `notebook to reproduce the figures
   <http://nbviewer.ipython.org/github/pvlib/pvsc2015/blob/master/paper.ipynb>`_)
 * J.S. Stein, W.F. Holmgren, J. Forbess, and C.W. Hansen,

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

@@ -33,6 +33,7 @@ Documentation
 ~~~~~~~~~~~~~
 
 * Added new terms to the variables documentation. (:issue:`195`)
+* Fix documentation build warnings. (:issue:`210`)
 
 
 Other

pvlib/irradiance.py

@@ -313,21 +313,22 @@ def beam_component(surface_tilt, surface_azimuth,
     return beam
 
 
-# ToDo: how to best structure this function? wholmgren 2014-11-03
 def total_irrad(surface_tilt, surface_azimuth,
                 apparent_zenith, azimuth,
                 dni, ghi, dhi, dni_extra=None, airmass=None,
                 albedo=.25, surface_type=None,
                 model='isotropic',
                 model_perez='allsitescomposite1990', **kwargs):
-    '''
+    r"""
     Determine diffuse irradiance from the sky on a
     tilted surface.
 
     .. math::
 
        I_{tot} = I_{beam} + I_{sky} + I_{ground}
 
+    See the transposition function documentation for details.
+
     Parameters
     ----------
     surface_tilt : float or Series.
@@ -359,15 +360,10 @@ def total_irrad(surface_tilt, surface_azimuth,
 
     Returns
     -------
-    DataFrame with columns ``'poa_global', 'poa_direct',
-    'poa_sky_diffuse', 'poa_ground_diffuse'``.
-
-    References
-    ----------
-    [1] Loutzenhiser P.G. et. al. "Empirical validation of models to compute
-    solar irradiance on inclined surfaces for building energy simulation"
-    2007, Solar Energy vol. 81. pp. 254-267
-    '''
+    irradiance: DataFrame
+        Contains columns ``'poa_global', 'poa_direct',
+        'poa_sky_diffuse', 'poa_ground_diffuse'``.
+    """
 
     pvl_logger.debug('planeofarray.total_irrad()')
 
@@ -415,7 +411,7 @@ def total_irrad(surface_tilt, surface_azimuth,
 
 # ToDo: keep this or not? wholmgren, 2014-11-03
 def globalinplane(aoi, dni, poa_sky_diffuse, poa_ground_diffuse):
-    '''
+    r'''
     Determine the three components on in-plane irradiance
 
     Combines in-plane irradaince compoents from the chosen diffuse translation,