diff --git a/docs/environment.yml b/docs/environment.yml
index 2fd1519aae..ed7c4027e0 100644
--- a/docs/environment.yml
+++ b/docs/environment.yml
@@ -1,6 +1,7 @@
-name: pvlib
+name: pvlibdocs
 dependencies:
     - python=2.7
+    - mock  # needed for local python 2.7 builds
     - numpy
     - scipy
     - pandas
@@ -8,7 +9,10 @@ dependencies:
     - ephem
     - numba
     - ipython=4.0.1
-    - sphinx
+    - ipywidgets
     - numpydoc
     - matplotlib
-    - seaborn
\ No newline at end of file
+    - seaborn
+    - sphinx=1.3.5  # same versions as rtd
+    - sphinx_rtd_theme=0.1.7
+    - docutils=0.12
diff --git a/docs/sphinx/source/classes.rst b/docs/sphinx/source/classes.rst
index f1fc154cd2..ccda434462 100644
--- a/docs/sphinx/source/classes.rst
+++ b/docs/sphinx/source/classes.rst
@@ -17,6 +17,7 @@ Location
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 PVSystem
 --------
@@ -24,6 +25,7 @@ PVSystem
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 ModelChain
 ----------
@@ -31,6 +33,7 @@ ModelChain
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 LocalizedPVSystem
 -----------------
@@ -38,6 +41,7 @@ LocalizedPVSystem
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 SingleAxisTracker
 -----------------
@@ -45,6 +49,7 @@ SingleAxisTracker
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
 LocalizedSingleAxisTracker
 --------------------------
@@ -52,4 +57,5 @@ LocalizedSingleAxisTracker
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
index caa171f292..11af074fb7 100644
--- a/docs/sphinx/source/index.rst
+++ b/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,
diff --git a/docs/sphinx/source/whatsnew/v0.4.0.txt b/docs/sphinx/source/whatsnew/v0.4.0.txt
index 719c314016..4c1e292f12 100644
--- a/docs/sphinx/source/whatsnew/v0.4.0.txt
+++ b/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
diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py
index 44ebfe27ba..aa6ac3f822 100644
--- a/pvlib/irradiance.py
+++ b/pvlib/irradiance.py
@@ -313,14 +313,13 @@ 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.
 
@@ -328,6 +327,8 @@ def total_irrad(surface_tilt, surface_azimuth,
 
        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,