DOC: switch from numpydoc to napoleon, render sphinx docs right (#691)

* DOC: fix napoleon, render sphinx docs right

* fix napoleon documentation issues

* set napoleon_use_rtype = False - for nicer style, combines return type
in parentheses after return name
* in bifacial use Parameters instead of Inputs
* in location use add newline and tab after kwargs parameter in two
places
* in model chain remove return and separate Notes
* in solarposition, add newline and tab after return type
* in tracking add Parameters to docstring for SingleAxisTracker

* remove numpydoc depndency

* remove from
    - INSTALL REQUIRES in setup.py
    - extensions in conf.py, also remove numpydoc directive
    - tutorials environment yml
* fix typo for singleaxis in tracking.py
* stickler CI
    - too long lines in tracking.py and modelchain.py
* fix some formatting, confusing markdown and rst code backticks

Signed-off-by: Mark Mikofski <[email protected]>

Author: mikofski

docs/environment.yml

@@ -13,7 +13,6 @@ dependencies:
     - ephem
     - numba
     - ipython=6.3
-    - numpydoc
     - matplotlib=2.2.2
     - siphon=0.7.0
     - sphinx=1.7.2

docs/sphinx/source/conf.py

@@ -40,8 +40,7 @@ def __getattr__(cls, name):
 
 # -- General configuration ------------------------------------------------
 
-# turns off numpydoc autosummary warnings
-numpydoc_show_class_members = False
+# use napoleon in lieu of numpydoc 2019-04-23
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
@@ -55,12 +54,14 @@ def __getattr__(cls, name):
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
-    'numpydoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting'
 ]
 
+napoleon_use_rtype = False  # group rtype on same line together with return
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/sphinx/source/contributing.rst

@@ -229,7 +229,9 @@ Documentation
 ~~~~~~~~~~~~~
 
 Documentation must be written in
-`numpydoc format <https://numpydoc.readthedocs.io/>`_.
+`numpydoc format <https://numpydoc.readthedocs.io/>`_ format which is rendered
+using the `Sphinx Napoleon extension
+<https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_.
 
 The numpydoc format includes a specification for the allowable input
 types. Python's `duck typing <https://en.wikipedia.org/wiki/Duck_typing>`_

pvlib/bifacial.py

@@ -20,8 +20,8 @@ def pvfactors_timeseries(
     Please refer to pvfactors online documentation for more details:
     https://sunpower.github.io/pvfactors/
 
-    Inputs
-    ------
+    Parameters
+    ----------
     solar_azimuth: numeric
         Sun's azimuth angles using pvlib's azimuth convention (deg)
     solar_zenith: numeric

pvlib/location.py

@@ -142,7 +142,8 @@ def get_solarposition(self, times, pressure=None, temperature=12,
             :py:func:`atmosphere.alt2pres` and ``self.altitude``.
         temperature : None, float, or array-like, default 12
 
-        kwargs passed to :py:func:`solarposition.get_solarposition`
+        kwargs
+            passed to :py:func:`solarposition.get_solarposition`
 
         Returns
         -------
@@ -178,8 +179,9 @@ def get_clearsky(self, times, model='ineichen', solar_position=None,
         dni_extra: None or numeric, default None
             If None, will be calculated from times.
 
-        kwargs passed to the relevant functions. Climatological values
-        are assumed in many cases. See source code for details!
+        kwargs
+            Extra parameters passed to the relevant functions. Climatological
+            values are assumed in many cases. See source code for details!
 
         Returns
         -------

pvlib/modelchain.py

@@ -798,21 +798,19 @@ def prepare_inputs(self, times=None, weather=None):
             Times at which to evaluate the model. Can be None if
             attribute `times` is already set.
         weather : None or DataFrame, default None
-            If None, the weather attribute is used. If the weather
-            attribute is also None assumes air temperature is 20 C, wind
+            If ``None``, the weather attribute is used. If the weather
+            attribute is also ``None`` assumes air temperature is 20 C, wind
             speed is 0 m/s and irradiation calculated from clear sky
-            data. Column names must be 'wind_speed', 'temp_air', 'dni',
-            'ghi', 'dhi'. Do not pass incomplete irradiation data. Use
-            method
+            data. Column names must be ``'wind_speed'``, ``'temp_air'``,
+            ``'dni'``, ``'ghi'``, ``'dhi'``. Do not pass incomplete irradiation
+            data. Use method
             :py:meth:`~pvlib.modelchain.ModelChain.complete_irradiance`
             instead.
 
-        Returns
-        -------
-        self
-
-        Assigns attributes: times, solar_position, airmass, total_irrad,
-        aoi
+        Notes
+        -----
+        Assigns attributes: ``times``, ``solar_position``, ``airmass``,
+        ``total_irrad``, `aoi`
         """
         if weather is not None:
             self.weather = weather

pvlib/pvsystem.py

@@ -247,8 +247,8 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
         model : String, default 'haydavies'
             Irradiance model.
 
-        **kwargs
-            Passed to :func:`irradiance.total_irrad`.
+        kwargs
+            Extra parameters passed to :func:`irradiance.total_irrad`.
 
         Returns
         -------
@@ -429,7 +429,7 @@ def sapm(self, effective_irradiance, temp_cell, **kwargs):
         aoi : Series
             Angle of incidence (degrees).
 
-        **kwargs
+        kwargs
             See pvsystem.sapm for details
 
         Returns

pvlib/solarposition.py

@@ -1278,7 +1278,8 @@ def solar_zenith_analytical(latitude, hourangle, declination):
 
     Returns
     -------
-    zenith : numeric Solar zenith angle in radians.
+    zenith : numeric
+        Solar zenith angle in radians.
 
     References
     ----------
@@ -1299,7 +1300,9 @@ def solar_zenith_analytical(latitude, hourangle, declination):
 
     See Also
     --------
-    declination_spencer71 declination_cooper69 hour_angle
+    declination_spencer71
+    declination_cooper69
+    hour_angle
     """
     return np.arccos(
         np.cos(declination) * np.cos(latitude) * np.cos(hourangle) +

pvlib/tracking.py

@@ -13,6 +13,9 @@ class SingleAxisTracker(PVSystem):
     """
     Inherits the PV modeling methods from :py:class:`~pvlib.pvsystem.PVSystem`.
 
+
+    Parameters
+    ----------
     axis_tilt : float, default 0
         The tilt of the axis of rotation (i.e, the y-axis defined by
         axis_azimuth) with respect to horizontal, in decimal degrees.
@@ -40,6 +43,7 @@ class SingleAxisTracker(PVSystem):
         2 meters wide, centered on the tracking axis, with 6 meters
         between the tracking axes has a gcr of 2/6=0.333. If gcr is not
         provided, a gcr of 2/7 is default. gcr must be <=1.
+
     """
 
     def __init__(self, axis_tilt=0, axis_azimuth=0,
@@ -67,6 +71,22 @@ def __repr__(self):
         return sat_repr + '\n' + pvsystem_repr
 
     def singleaxis(self, apparent_zenith, apparent_azimuth):
+        """
+        Get tracking data. See :py:func:`pvlib.tracking.singleaxis` more
+        detail.
+
+        Parameters
+        ----------
+        apparent_zenith : float, 1d array, or Series
+            Solar apparent zenith angles in decimal degrees.
+
+        apparent_azimuth : float, 1d array, or Series
+            Solar apparent azimuth angles in decimal degrees.
+
+        Returns
+        -------
+        tracking data
+        """
         tracking_data = singleaxis(apparent_zenith, apparent_azimuth,
                                    self.axis_tilt, self.axis_azimuth,
                                    self.max_angle,

setup.py

@@ -46,8 +46,7 @@
 EXTRAS_REQUIRE = {
     'optional': ['scipy', 'tables', 'numba', 'siphon', 'netcdf4',
                  'ephem', 'cython', 'pvfactors'],
-    'doc': ['sphinx', 'ipython', 'sphinx_rtd_theme', 'numpydoc',
-            'matplotlib'],
+    'doc': ['sphinx', 'ipython', 'sphinx_rtd_theme', 'matplotlib'],
     'test': TESTS_REQUIRE
 }
 EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), [])))