Fix most sphinx warnings (#912)

* fix underline in examples/plot_singlediode.py

* move references out of the first sentence

* pin docutils at 0.15.2 in doc requirements

Author: kandersolar

docs/examples/plot_singlediode.py

@@ -1,6 +1,6 @@
 """
 Calculating a module's IV curves
-=====================
+================================
 
 Examples of modeling IV curves using a single-diode circuit equivalent model.
 """

pvlib/bifacial.py

@@ -18,7 +18,8 @@ def pvfactors_timeseries(
     """
     Calculate front and back surface plane-of-array irradiance on
     a fixed tilt or single-axis tracker PV array configuration, and using
-    the open-source "pvfactors" package [1]_.
+    the open-source "pvfactors" package.  pvfactors implements the model
+    described in [1]_.
     Please refer to pvfactors online documentation for more details:
     https://sunpower.github.io/pvfactors/
 

pvlib/clearsky.py

@@ -405,7 +405,7 @@ def simplified_solis(apparent_elevation, aod700=0.1, precipitable_water=1.,
                      pressure=101325., dni_extra=1364.):
     """
     Calculate the clear sky GHI, DNI, and DHI according to the
-    simplified Solis model [1]_.
+    simplified Solis model.
 
     Reference [1]_ describes the accuracy of the model as being 15, 20,
     and 18 W/m^2 for the beam, global, and diffuse components. Reference
@@ -604,7 +604,7 @@ def detect_clearsky(measured, clearsky, times, window_length,
                     return_components=False):
     """
     Detects clear sky times according to the algorithm developed by Reno
-    and Hansen for GHI measurements [1]. The algorithm was designed and
+    and Hansen for GHI measurements. The algorithm [1]_ was designed and
     validated for analyzing GHI time series only. Users may attempt to
     apply it to other types of time series data using different filter
     settings, but should be skeptical of the results.

pvlib/iotools/crn.py

@@ -42,7 +42,8 @@
 
 def read_crn(filename):
     """
-    Read NOAA USCRN [1]_ [2]_ fixed-width file into pandas dataframe.
+    Read a NOAA USCRN fixed-width file into pandas dataframe.  The CRN is
+    described in [1]_ and [2]_.
 
     Parameters
     ----------

pvlib/iotools/midc.py

@@ -154,7 +154,7 @@ def format_index_raw(data):
 
 def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
     """Read in National Renewable Energy Laboratory Measurement and
-    Instrumentation Data Center [1]_ weather data.
+    Instrumentation Data Center weather data.  The MIDC is described in [1]_.
 
     Parameters
     ----------

pvlib/iotools/psm3.py

@@ -24,8 +24,8 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
              leap_day=False, full_name=PVLIB_PYTHON, affiliation=PVLIB_PYTHON,
              timeout=30):
     """
-    Retrieve NSRDB [1]_ PSM3 timeseries weather data from the PSM3 API [2]_
-    [3]_.
+    Retrieve NSRDB PSM3 timeseries weather data from the PSM3 API.  The NSRDB
+    is described in [1]_ and the PSM3 API is described in [2]_ and [3]_.
 
     Parameters
     ----------
@@ -147,7 +147,8 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
 
 def parse_psm3(fbuf):
     """
-    Parse an NSRDB [1]_ PSM3 weather file (formatted as SAM CSV [2]_).
+    Parse an NSRDB PSM3 weather file (formatted as SAM CSV).  The NSRDB
+    is described in [1]_ and the SAM CSV format is described in [2]_.
 
     Parameters
     ----------
@@ -269,7 +270,8 @@ def parse_psm3(fbuf):
 
 def read_psm3(filename):
     """
-    Read an NSRDB [1]_ PSM3 weather file (formatted as SAM CSV [2]_).
+    Read an NSRDB PSM3 weather file (formatted as SAM CSV).  The NSRDB
+    is described in [1]_ and the SAM CSV format is described in [2]_.
 
     Parameters
     ----------

pvlib/iotools/pvgis.py

@@ -28,7 +28,7 @@ def get_pvgis_tmy(lat, lon, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None, url=URL,
                   timeout=30):
     """
-    Get TMY data from PVGIS [1]_. For more information see the PVGIS TMY tool
+    Get TMY data from PVGIS. For more information see the PVGIS [1]_ TMY tool
     documentation [2]_.
 
     Parameters

pvlib/iotools/solrad.py

@@ -49,7 +49,8 @@
 
 def read_solrad(filename):
     """
-    Read NOAA SOLRAD [1]_ [2]_ fixed-width file into pandas dataframe.
+    Read NOAA SOLRAD fixed-width file into pandas dataframe.  The SOLRAD
+    network is described in [1]_ and [2]_.
 
     Parameters
     ----------

pvlib/iotools/srml.py

@@ -26,7 +26,8 @@
 
 def read_srml(filename):
     """
-    Read University of Oregon SRML[1]_ 1min .tsv file into pandas dataframe.
+    Read University of Oregon SRML 1min .tsv file into pandas dataframe.  The
+    SRML is described in [1]_.
 
     Parameters
     ----------
@@ -166,8 +167,8 @@ def format_index(df):
 
 
 def read_srml_month_from_solardat(station, year, month, filetype='PO'):
-    """Request a month of SRML[1] data from solardat and read it into
-    a Dataframe.
+    """Request a month of SRML data from solardat and read it into
+    a Dataframe.  The SRML is described in [1]_.
 
     Parameters
     ----------

pvlib/iotools/surfrad.py

@@ -38,7 +38,8 @@
 
 
 def read_surfrad(filename, map_variables=True):
-    """Read in a daily NOAA SURFRAD[1]_ file.
+    """Read in a daily NOAA SURFRAD file.  The SURFRAD network is
+    described in [1]_.
 
     Parameters
     ----------