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
     ----------

pvlib/irradiance.py

@@ -1226,7 +1226,9 @@ def clearness_index(ghi, solar_zenith, extra_radiation, min_cos_zenith=0.065,
 def clearness_index_zenith_independent(clearness_index, airmass,
                                        max_clearness_index=2.0):
     """
-    Calculate the zenith angle independent clearness index [1]_.
+    Calculate the zenith angle independent clearness index.
+
+    See [1]_ for details.
 
     Parameters
     ----------
@@ -1764,8 +1766,9 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times,
                model='perez', model_perez='allsitescomposite1990',
                calculate_gt_90=True, max_iterations=30):
     """
-    Determine GHI, DNI, DHI from POA global using the GTI DIRINT model
-    [1]_.
+    Determine GHI, DNI, DHI from POA global using the GTI DIRINT model.
+
+    The GTI DIRINT model is described in [1]_.
 
     .. warning::
 

pvlib/ivtools.py

@@ -264,8 +264,8 @@ def fit_sdm_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
                    cells_in_series, EgRef=1.121, dEgdT=-0.0002677,
                    temp_ref=25, irrad_ref=1000, root_kwargs={}):
     """
-    Calculates the parameters for the De Soto single diode model using the
-    procedure described in [1]_. This procedure has the advantage of
+    Calculates the parameters for the De Soto single diode model.
+    This procedure (described in [1]_) has the advantage of
     using common specifications given by manufacturers in the
     datasheets of PV modules.
 

pvlib/pvsystem.py

@@ -1205,7 +1205,7 @@ def calcparams_cec(effective_irradiance, temp_cell,
     '''
     Calculates five parameter values for the single diode equation at
     effective irradiance and cell temperature using the CEC
-    model described in [1]_. The CEC model differs from the De soto et al.
+    model. The CEC model [1]_ differs from the De soto et al.
     model [3]_ by the parameter Adjust. The five values returned by
     calcparams_cec can be used by singlediode to calculate an IV curve.
 
@@ -1325,8 +1325,9 @@ def calcparams_pvsyst(effective_irradiance, temp_cell,
     '''
     Calculates five parameter values for the single diode equation at
     effective irradiance and cell temperature using the PVsyst v6
-    model described in [1]_, [2]_, [3]_. The five values returned by
-    calcparams_pvsyst can be used by singlediode to calculate an IV curve.
+    model.  The PVsyst v6 model is described in [1]_, [2]_, [3]_.
+    The five values returned by calcparams_pvsyst can be used by singlediode
+    to calculate an IV curve.
 
     Parameters
     ----------
@@ -2662,7 +2663,7 @@ def scale_voltage_current_power(data, voltage=1, current=1):
 
 def pvwatts_dc(g_poa_effective, temp_cell, pdc0, gamma_pdc, temp_ref=25.):
     r"""
-    Implements NREL's PVWatts DC power model [1]_:
+    Implements NREL's PVWatts DC power model. The PVWatts DC model [1]_ is:
 
     .. math::
 
@@ -2713,7 +2714,8 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
                    connections=0.5, lid=1.5, nameplate_rating=1, age=0,
                    availability=3):
     r"""
-    Implements NREL's PVWatts system loss model [1]_:
+    Implements NREL's PVWatts system loss model.
+    The PVWatts loss model [1]_ is:
 
     .. math::
 
@@ -2764,7 +2766,8 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
 
 def pvwatts_ac(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     r"""
-    Implements NREL's PVWatts inverter model [1]_.
+    Implements NREL's PVWatts inverter model.
+    The PVWatts inverter model [1]_ is:
 
     .. math::
 

pvlib/singlediode.py

@@ -72,7 +72,7 @@ def bishop88(diode_voltage, photocurrent, saturation_current,
              NsVbi=np.Inf, gradients=False):
     """
     Explicit calculation of points on the IV curve described by the single
-    diode equation [1]_.
+    diode equation.  Values are calculated as described in [1]_.
 
     .. warning::
        * Do not use ``d2mutau`` with CEC coefficients.

pvlib/solarposition.py

@@ -277,7 +277,9 @@ def spa_python(time, latitude, longitude,
                atmos_refract=None, how='numpy', numthreads=4, **kwargs):
     """
     Calculate the solar position using a python implementation of the
-    NREL SPA algorithm described in [1].
+    NREL SPA algorithm.
+
+    The details of the NREL SPA algorithm are described in [1]_.
 
     If numba is installed, the functions can be compiled to
     machine code and the function can be multithreaded.
@@ -385,7 +387,9 @@ def sun_rise_set_transit_spa(times, latitude, longitude, how='numpy',
                              delta_t=67.0, numthreads=4):
     """
     Calculate the sunrise, sunset, and sun transit times using the
-    NREL SPA algorithm described in [1].
+    NREL SPA algorithm.
+
+    The details of the NREL SPA algorithm are described in [1]_.
 
     If numba is installed, the functions can be compiled to
     machine code and the function can be multithreaded.
@@ -958,7 +962,9 @@ def pyephem_earthsun_distance(time):
 def nrel_earthsun_distance(time, how='numpy', delta_t=67.0, numthreads=4):
     """
     Calculates the distance from the earth to the sun using the
-    NREL SPA algorithm described in [1]_.
+    NREL SPA algorithm.
+
+    The details of the NREL SPA algorithm are described in [1]_.
 
     Parameters
     ----------
@@ -1131,9 +1137,11 @@ def equation_of_time_pvcdrom(dayofyear):
 
 def declination_spencer71(dayofyear):
     """
-    Solar declination from Duffie & Beckman [1] and attributed to
+    Solar declination from Duffie & Beckman and attributed to
     Spencer (1971) and Iqbal (1983).
 
+    See [1]_ for details.
+
     .. warning::
         Return units are radians, not degrees.
 
@@ -1173,7 +1181,9 @@ def declination_spencer71(dayofyear):
 
 def declination_cooper69(dayofyear):
     """
-    Solar declination from Duffie & Beckman [1] and attributed to Cooper (1969)
+    Solar declination from Duffie & Beckman and attributed to Cooper (1969).
+
+    See [1]_ for details.
 
     .. warning::
         Return units are radians, not degrees.

pvlib/temperature.py

@@ -33,7 +33,9 @@ def _temperature_model_params(model, parameter_set):
 def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
               irrad_ref=1000):
     r'''
-    Calculate cell temperature per the Sandia PV Array Performance Model [1]_.
+    Calculate cell temperature per the Sandia PV Array Performance Model.
+
+    See [1]_ for details on the Sandia Array Performance Model.
 
     Parameters
     ----------
@@ -120,7 +122,9 @@ def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
 def sapm_module(poa_global, temp_air, wind_speed, a, b):
     r'''
     Calculate module back surface temperature per the Sandia PV Array
-    Performance Model [1]_.
+    Performance Model.
+
+    See [1]_ for details on the Sandia Array Performance Model.
 
     Parameters
     ----------
@@ -273,9 +277,9 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
 
 def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
     '''
-    Calculate cell or module temperature using an empirical heat loss factor
-    model as proposed by Faiman [1]_ and adopted in the IEC 61853
-    standards [2]_ and [3]_.
+    Calculate cell or module temperature using the Faiman model.  The Faiman
+    model uses an empirical heat loss factor model [1]_ and is adopted in the
+    IEC 61853 standards [2]_ and [3]_.
 
     Usage of this model in the IEC 61853 standard does not distinguish
     between cell and module temperature.

pvlib/tracking.py

@@ -249,9 +249,10 @@ def singleaxis(apparent_zenith, apparent_azimuth,
                axis_tilt=0, axis_azimuth=0, max_angle=90,
                backtrack=True, gcr=2.0/7.0):
     """
-    Determine the rotation angle of a single axis tracker using the
-    equations in [1]_ when given a particular sun zenith and azimuth
-    angle. backtracking may be specified, and if so, a ground coverage
+    Determine the rotation angle of a single axis tracker when given a
+    particular sun zenith and azimuth angle. See [1]_ for details about
+    the equations.
+    Backtracking may be specified, and if so, a ground coverage
     ratio is required.
 
     Rotation angle is determined in a panel-oriented coordinate system.

setup.py

@@ -47,7 +47,7 @@
     'optional': ['ephem', 'cython', 'netcdf4', 'nrel-pysam', 'numba',
                  'pvfactors', 'scipy', 'siphon', 'tables'],
     'doc': ['ipython', 'matplotlib', 'sphinx == 1.8.5', 'sphinx_rtd_theme',
-            'sphinx-gallery'],
+            'sphinx-gallery', 'docutils == 0.15.2'],
     'test': TESTS_REQUIRE
 }
 EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), [])))