From 89bae34bd10b128096d8cf741ab914f6413bae47 Mon Sep 17 00:00:00 2001 From: Mark Mikofski Date: Tue, 23 Apr 2019 01:12:57 -0700 Subject: [PATCH 1/3] DOC: fix napoleon, render sphinx docs right --- docs/sphinx/source/conf.py | 3 ++- pvlib/solarposition.py | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index b162eee4f4..9d899cdc3a 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -55,8 +55,9 @@ def __getattr__(cls, name): 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks', - 'numpydoc', + 'sphinx.ext.napoleon', 'sphinx.ext.autosummary', + 'numpydoc', 'IPython.sphinxext.ipython_directive', 'IPython.sphinxext.ipython_console_highlighting' ] diff --git a/pvlib/solarposition.py b/pvlib/solarposition.py index e2dc536936..b59106d378 100644 --- a/pvlib/solarposition.py +++ b/pvlib/solarposition.py @@ -1299,7 +1299,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) + From 5f4b00ca8fcc97ed83a3c3d774d9e39bcdc57746 Mon Sep 17 00:00:00 2001 From: Mark Mikofski Date: Tue, 23 Apr 2019 15:14:22 -0700 Subject: [PATCH 2/3] 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 --- docs/sphinx/source/conf.py | 2 ++ pvlib/bifacial.py | 4 ++-- pvlib/location.py | 8 +++++--- pvlib/modelchain.py | 18 ++++++++---------- pvlib/pvsystem.py | 6 +++--- pvlib/solarposition.py | 3 ++- pvlib/tracking.py | 19 +++++++++++++++++++ 7 files changed, 41 insertions(+), 19 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 9d899cdc3a..dcaf013e8d 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -62,6 +62,8 @@ def __getattr__(cls, name): 'IPython.sphinxext.ipython_console_highlighting' ] +napoleon_use_rtype = False + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/pvlib/bifacial.py b/pvlib/bifacial.py index 4f63aa0922..b273dcf0cb 100644 --- a/pvlib/bifacial.py +++ b/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 diff --git a/pvlib/location.py b/pvlib/location.py index 4d44dcf8ef..68b2062907 100644 --- a/pvlib/location.py +++ b/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 ------- diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index b1cd6ecfa7..99b94b03d9 100644 --- a/pvlib/modelchain.py +++ b/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 + 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 diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 5ee22debd3..82380622e1 100644 --- a/pvlib/pvsystem.py +++ b/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 diff --git a/pvlib/solarposition.py b/pvlib/solarposition.py index b59106d378..15b8b26665 100644 --- a/pvlib/solarposition.py +++ b/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 ---------- diff --git a/pvlib/tracking.py b/pvlib/tracking.py index 67e0b2e786..2eeb9aea63 100644 --- a/pvlib/tracking.py +++ b/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,21 @@ 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 + ------- + traciking data + """ tracking_data = singleaxis(apparent_zenith, apparent_azimuth, self.axis_tilt, self.axis_azimuth, self.max_angle, From fa1cab390381101ca2b07d88fb62a0f1db511df7 Mon Sep 17 00:00:00 2001 From: Mark Mikofski Date: Tue, 23 Apr 2019 21:15:24 -0700 Subject: [PATCH 3/3] 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 --- docs/environment.yml | 1 - docs/sphinx/source/conf.py | 6 ++---- docs/sphinx/source/contributing.rst | 4 +++- pvlib/modelchain.py | 10 +++++----- pvlib/tracking.py | 5 +++-- setup.py | 3 +-- 6 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/environment.yml b/docs/environment.yml index aaa0058a02..e7eaa0e36e 100644 --- a/docs/environment.yml +++ b/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 diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index dcaf013e8d..d09c7a71e9 100644 --- a/docs/sphinx/source/conf.py +++ b/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' @@ -57,12 +56,11 @@ def __getattr__(cls, name): 'sphinx.ext.extlinks', 'sphinx.ext.napoleon', 'sphinx.ext.autosummary', - 'numpydoc', 'IPython.sphinxext.ipython_directive', 'IPython.sphinxext.ipython_console_highlighting' ] -napoleon_use_rtype = False +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'] diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 2819a20248..25e82d6017 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -229,7 +229,9 @@ Documentation ~~~~~~~~~~~~~ Documentation must be written in -`numpydoc format `_. +`numpydoc format `_ format which is rendered +using the `Sphinx Napoleon extension +`_. The numpydoc format includes a specification for the allowable input types. Python's `duck typing `_ diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index 99b94b03d9..46c312d054 100644 --- a/pvlib/modelchain.py +++ b/pvlib/modelchain.py @@ -801,16 +801,16 @@ def prepare_inputs(self, times=None, weather=None): 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. Notes ----- - Assigns attributes: `times`, `solar_position`, `airmass`, `total_irrad`, - `aoi` + Assigns attributes: ``times``, ``solar_position``, ``airmass``, + ``total_irrad``, `aoi` """ if weather is not None: self.weather = weather diff --git a/pvlib/tracking.py b/pvlib/tracking.py index 2eeb9aea63..a69b707e82 100644 --- a/pvlib/tracking.py +++ b/pvlib/tracking.py @@ -72,7 +72,8 @@ def __repr__(self): def singleaxis(self, apparent_zenith, apparent_azimuth): """ - Get tracking data. See :py:func:`pvlib.tracking.singleaxis` more detail. + Get tracking data. See :py:func:`pvlib.tracking.singleaxis` more + detail. Parameters ---------- @@ -84,7 +85,7 @@ def singleaxis(self, apparent_zenith, apparent_azimuth): Returns ------- - traciking data + tracking data """ tracking_data = singleaxis(apparent_zenith, apparent_azimuth, self.axis_tilt, self.axis_azimuth, diff --git a/setup.py b/setup.py index e1b4cc6e43..1f79de1018 100755 --- a/setup.py +++ b/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(), [])))