Skip to content

Docstring formatting #833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wholmgren merged 37 commits into from
Dec 16, 2019
Merged

Docstring formatting #833

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
c7ea688
improve docstring sphinx rendering in ModelChain methods
kevinsa5 Dec 10, 2019
bc09814
improve docstring sphinx rendering in Location.from_tmy
kevinsa5 Dec 10, 2019
4cb0b0d
improve docstring sphinx rendering in tracking.singleaxis
kevinsa5 Dec 10, 2019
106ab87
improve docstring sphinx rendering in iotools.midc.read_midc
kevinsa5 Dec 10, 2019
9520610
improve docstring sphinx rendering in ivtools functions
kevinsa5 Dec 10, 2019
af11331
remove duplicate pvwatts_losses entry in api.rst
kevinsa5 Dec 10, 2019
0ae798e
improve docstring sphinx rendering in clearsky functions
kevinsa5 Dec 10, 2019
dd3c614
add whatsnew entry
kevinsa5 Dec 11, 2019
13a699b
update formatting of "Assigns attributes" info in modelchain.py docst…
kevinsa5 Dec 11, 2019
5bbf06c
fix capitalization in iotools.midc.read_midc
kevinsa5 Dec 11, 2019
a928c41
improve docstring formatting for return value dict keys in ivtools.fi…
kevinsa5 Dec 11, 2019
864e517
simplify Location.from_tmy docstring
kevinsa5 Dec 12, 2019
dfef019
pin sphinx version at 1.8.5 in setup.py
kevinsa5 Dec 13, 2019
a15484f
make solarposition.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
4257f97
make clearsky.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
f62a376
make atmosphere.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
ec5dfc5
make irradiance.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
336fb47
make iam.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
f6d683f
make temperature.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
81103ad
make pvsystem.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
9a38a02
make singlediode.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
ba530f7
make ivtools.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
27292af
make tracking.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
a6f6c2b
make tmy.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
1eb5122
make epw.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
bdab55c
make srml.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
e1f6168
make surfrad.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
37ba6c1
make psm3.py footnotes compatible with numpydoc
kevinsa5 Dec 13, 2019
9309522
fix typo in pvsyst_cell docstring footnote
kevinsa5 Dec 13, 2019
d62e7c4
add sphinx suppress_warnings entry for unreferenced footnote warnings
kevinsa5 Dec 13, 2019
0962a4e
make the stickler happy
kevinsa5 Dec 13, 2019
57a8098
fix improper reference format in pvsystem.calcparams_pvsyst docstring
kevinsa5 Dec 13, 2019
0c20996
remove TMY module from api.rst and add pvsystem.adrinverter
kevinsa5 Dec 14, 2019
6c9203c
add link to github issue about suppressing sphinx warnings
kevinsa5 Dec 14, 2019
5700205
Merge branch 'master' into docstring_formatting
kevinsa5 Dec 14, 2019
de881cc
fix lint issue in pvsystem.py and make pvsystem.adrinverter docstring…
kevinsa5 Dec 16, 2019
6c2cf74
Merge branch 'docstring_formatting' of https://github.com/kevinsa5/pv…
kevinsa5 Dec 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/sphinx/source/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,6 @@ PVWatts model
pvsystem.pvwatts_dc
pvsystem.pvwatts_ac
pvsystem.pvwatts_losses
pvsystem.pvwatts_losses

Functions for fitting PV models
-------------------------------
Expand Down
6 changes: 6 additions & 0 deletions docs/sphinx/source/whatsnew/v0.7.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,11 @@ Documentation
used. (:issue:`785`)
* Note warning about _TMY3.epw files retrieved from energyplus.net in docstring
of `epw.read_epw`
* Improved sphinx rendering of API reference entries for `clearsky.ineichen`,
`clearsky.haurwitz`, `tracking.singleaxis`, `iotools.read_midc`,
`Location.from_tmy`, `ModelChain.run_model`, `ModelChain.complete_irradiance`,
and `ModelChain.prepare_inputs`
* Removed duplicate `pvwatts_losses` entry in `api.rst`

Removal of prior version deprecations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -202,3 +207,4 @@ Contributors
* Joseph Ranalli (:ghuser:`jranalli`)
* Tony Lorenzo (:ghuser:`alorenzo175`)
* Todd Karin (:ghuser:`toddkarin`)
* Kevin Anderson (:ghuser:`kevinsa5`)
24 changes: 12 additions & 12 deletions pvlib/clearsky.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,22 +65,22 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity,
References
----------
[1] P. Ineichen and R. Perez, "A New airmass independent formulation for
the Linke turbidity coefficient", Solar Energy, vol 73, pp. 151-157,
2002.
the Linke turbidity coefficient", Solar Energy, vol 73, pp. 151-157,
2002.
Copy link
Member

@wholmgren wholmgren Dec 11, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Neither the current format nor the proposed change is consistent with references section of numpydoc

Copy link
Contributor Author

@kevinsa5 kevinsa5 Dec 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair, but I am having zero success with doing it the "right way" and getting the results to look any better than the ones here: https://pvlib-python.readthedocs.io/en/stable/generated/pvlib.atmosphere.first_solar_spectral_correction.html

Is that how references are supposed to look?

Copy link
Member

@wholmgren wholmgren Dec 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm... They should look like the format in the numpydoc example. I don't know why they do not. I poked at the html/css. I think numpydoc is writing out the correct rst and sphinx is processing it into the correct html, so I'm guessing it's related to the css. It could be specific to the readthedocs sphinx theme, but that's just a guess.

So, none of the formats are ideal. I have a slight preference for sticking with the numpydoc format and hoping that someone, somewhere, fixes some bug for us. But I'm also ok with your "plain text" approach.

Copy link
Contributor Author

@kevinsa5 kevinsa5 Dec 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It could be specific to the readthedocs sphinx theme, but that's just a guess.

Good guess! Looks like it's an incompatibility between sphinx_rtd_theme and sphinx 2.0+: readthedocs/sphinx_rtd_theme#741. It's a bit of a rabbit hole, but I've found two workarounds:

  • Using sphinx <2.0 fixes the reference rendering, or at least v1.8.5 does for me locally. Interestingly, RTD is installing 1.8.5 first and then replacing it with 2.2.2 -- see the most recent RTD build log, ctrl-F "Successfully uninstalled Sphinx-1.8.5". I'm guessing that the sphinx=1.7.2 in the environment.yml file isn't being respected because that file is used for conda installs, but readthedocs.yml says to use pip and install all extra requirements, which according to setup.py includes sphinx without a version constraint. So I'd guess that pinning sphinx at a pre-2.0 version in setup.py would change the version RTD ends up using. RTD also encourages pinning specific versions of sphinx, see the blue Note section here: https://docs.readthedocs.io/en/stable/builds.html#understanding-what-s-going-on
  • Apparently sphinx 2.0+ switched to HTML5 output, but the old HTML4 writer is still available. I tried it out locally and it also fixes the references problem.

Both of these are a little heavy handed and have an effect on how the rest of the docs are rendered so I wanted to get feedback on whether this seemed like a good idea or if you'd prefer to just wait for the theme to fix it on their end. Either way, I'll standardize the docstring references to the numpydoc format. Some other functions already had the plaintext version (e.g. clearsky.bird) so I'll change those as well.

Copy link
Member

@cwhanse cwhanse Dec 12, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

standardize the docstring references to the numpydoc format.

+1 here.

Copy link
Member

@wholmgren wholmgren Dec 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct about the conda file being ignored. I’m ok with either work around.


[2] R. Perez et. al., "A New Operational Model for Satellite-Derived
Irradiances: Description and Validation", Solar Energy, vol 73, pp.
307-317, 2002.
Irradiances: Description and Validation", Solar Energy, vol 73, pp.
307-317, 2002.

[3] M. Reno, C. Hansen, and J. Stein, "Global Horizontal Irradiance Clear
Sky Models: Implementation and Analysis", Sandia National
Laboratories, SAND2012-2389, 2012.
Sky Models: Implementation and Analysis", Sandia National
Laboratories, SAND2012-2389, 2012.

[4] http://www.soda-is.com/eng/services/climat_free_eng.php#c5 (obtained
July 17, 2012).
July 17, 2012).

[5] J. Remund, et. al., "Worldwide Linke Turbidity Information", Proc.
ISES Solar World Congress, June 2003. Goteborg, Sweden.
ISES Solar World Congress, June 2003. Goteborg, Sweden.
'''

# ghi is calculated using either the equations in [1] by setting
Expand Down Expand Up @@ -378,14 +378,14 @@ def haurwitz(apparent_zenith):
----------

[1] B. Haurwitz, "Insolation in Relation to Cloudiness and Cloud
Density," Journal of Meteorology, vol. 2, pp. 154-166, 1945.
Density," Journal of Meteorology, vol. 2, pp. 154-166, 1945.

[2] B. Haurwitz, "Insolation in Relation to Cloud Type," Journal of
Meteorology, vol. 3, pp. 123-124, 1946.
Meteorology, vol. 3, pp. 123-124, 1946.

[3] M. Reno, C. Hansen, and J. Stein, "Global Horizontal Irradiance Clear
Sky Models: Implementation and Analysis", Sandia National
Laboratories, SAND2012-2389, 2012.
Sky Models: Implementation and Analysis", Sandia National
Laboratories, SAND2012-2389, 2012.
'''

cos_zenith = tools.cosd(apparent_zenith.values)
Expand Down
6 changes: 3 additions & 3 deletions pvlib/iotools/midc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,9 +180,9 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
The `variable_map` argument should map fields from MIDC data to pvlib
names.

e.g. If a MIDC file contains the variable 'Global Horizontal [W/m^2]',
passing the dictionary below will rename the column to 'ghi' in
the returned Dataframe.
E.g. if a MIDC file contains the variable 'Global Horizontal [W/m^2]',
passing the dictionary below will rename the column to 'ghi' in
the returned Dataframe.

{'Global Horizontal [W/m^2]': 'ghi'}

Expand Down
128 changes: 62 additions & 66 deletions pvlib/ivtools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,36 +40,35 @@ def fit_sdm_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,

Returns
-------
tuple of the following elements:
I_L_ref : float
The light-generated current (or photocurrent) at reference
conditions [A]

* I_L_ref : float
The light-generated current (or photocurrent) at reference
conditions [A]
I_o_ref : float
The dark or diode reverse saturation current at reference
conditions [A]

* I_o_ref : float
The dark or diode reverse saturation current at reference
conditions [A]
R_sh_ref : float
The shunt resistance at reference conditions, in ohms.

* R_sh_ref : float
The shunt resistance at reference conditions, in ohms.
R_s : float
The series resistance at reference conditions, in ohms.

* R_s : float
The series resistance at reference conditions, in ohms.
a_ref : float
The product of the usual diode ideality factor ``n`` (unitless),
number of cells in series ``Ns``, and cell thermal voltage at
reference conditions [V]

* a_ref : float
The product of the usual diode ideality factor ``n`` (unitless),
number of cells in series ``Ns``, and cell thermal voltage at
reference conditions [V]

* Adjust : float
The adjustment to the temperature coefficient for short circuit
current, in percent.
Adjust : float
The adjustment to the temperature coefficient for short circuit
current, in percent.

Raises
------
ImportError if NREL-PySAM is not installed.

RuntimeError if parameter extraction is not successful.
ImportError
If NREL-PySAM is not installed.
RuntimeError
If parameter extraction is not successful.

Notes
-----
Expand Down Expand Up @@ -147,23 +146,22 @@ def fit_sde_sandia(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,

Returns
-------
tuple of the following elements:

* photocurrent : float
photocurrent [A]
* saturation_current : float
dark (saturation) current [A]
* resistance_shunt : float
shunt (parallel) resistance, in ohms
* resistance_series : float
series resistance, in ohms
* nNsVth : float
product of thermal voltage ``Vth`` [V], diode ideality factor
``n``, and number of series cells ``Ns``
photocurrent : float
photocurrent [A]
saturation_current : float
dark (saturation) current [A]
resistance_shunt : float
shunt (parallel) resistance, in ohms
resistance_series : float
series resistance, in ohms
nNsVth : float
product of thermal voltage ``Vth`` [V], diode ideality factor
``n``, and number of series cells ``Ns``

Raises
------
RuntimeError if parameter extraction is not successful.
RuntimeError
If parameter extraction is not successful.

Notes
-----
Expand Down Expand Up @@ -314,36 +312,34 @@ def fit_sdm_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,

Returns
-------
Tuple of the following elements:

* Dictionary with the following elements:
I_L_ref: float
Light-generated current at reference conditions [A]
I_o_ref: float
Diode saturation current at reference conditions [A]
R_s: float
Series resistance [ohms]
R_sh_ref: float
Shunt resistance at reference conditions [ohms].
a_ref: float
Modified ideality factor at reference conditions.
The product of the usual diode ideality factor (n, unitless),
number of cells in series (Ns), and cell thermal voltage at
specified effective irradiance and cell temperature.
alpha_sc: float
The short-circuit current (i_sc) temperature coefficient of the
module [A/K].
EgRef: float
Energy of bandgap of semi-conductor used [eV]
dEgdT: float
Variation of bandgap according to temperature [eV/K]
irrad_ref: float
Reference irradiance condition [W/m2]
temp_ref: float
Reference temperature condition [C]
* scipy.optimize.OptimizeResult
Optimization result of scipy.optimize.root().
See scipy.optimize.OptimizeResult for more details.
Dictionary with the following elements:
* ``I_L_ref`` (float) --
Light-generated current at reference conditions [A]
* ``I_o_ref`` (float) --
Diode saturation current at reference conditions [A]
* ``R_s`` (float) --
Series resistance [ohms]
* ``R_sh_ref`` (float) --
Shunt resistance at reference conditions [ohms].
* ``a_ref`` (float) --
Modified ideality factor at reference conditions.
The product of the usual diode ideality factor (n, unitless),
number of cells in series (Ns), and cell thermal voltage at
specified effective irradiance and cell temperature.
* ``alpha_sc`` (float) --
The short-circuit current (i_sc) temperature coefficient of the
module [A/K].
* ``EgRef`` (float) --
Energy of bandgap of semi-conductor used [eV]
* ``dEgdT`` (float) --
Variation of bandgap according to temperature [eV/K]
* ``irrad_ref`` (float) --
Reference irradiance condition [W/m2]
* ``temp_ref`` (float) --
Reference temperature condition [C]
scipy.optimize.OptimizeResult
Optimization result of scipy.optimize.root().
See scipy.optimize.OptimizeResult for more details.

References
----------
Expand Down
5 changes: 3 additions & 2 deletions pvlib/location.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,9 @@ def from_tmy(cls, tmy_metadata, tmy_data=None, **kwargs):

Returns
-------
Location object (or the child class of Location that you
called this method from).
new_object
Location object (or the child class of Location that you
called this method from).
"""
# not complete, but hopefully you get the idea.
# might need code to handle the difference between tmy2 and tmy3
Expand Down
15 changes: 10 additions & 5 deletions pvlib/modelchain.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -757,7 +757,9 @@ def complete_irradiance(self, weather, times=None):
-------
self

Assigns attributes: weather
Notes
-----
Assigns attributes: ``weather``

Examples
--------
Expand Down Expand Up @@ -833,7 +835,7 @@ def prepare_inputs(self, weather, times=None):
Notes
-----
Assigns attributes: ``solar_position``, ``airmass``,
``total_irrad``, `aoi`
``total_irrad``, ``aoi``

See also
--------
Expand Down Expand Up @@ -924,9 +926,12 @@ def run_model(self, weather, times=None):
-------
self

Assigns attributes: solar_position, airmass, irradiance,
total_irrad, effective_irradiance, weather, cell_temperature, aoi,
aoi_modifier, spectral_modifier, dc, ac, losses.
Notes
-----
Assigns attributes: ``solar_position``, ``airmass``, ``irradiance``,
``total_irrad``, ``effective_irradiance``, ``weather``,
``cell_temperature``, ``aoi``, ``aoi_modifier``, ``spectral_modifier``,
``dc``, ``ac``, ``losses``.
"""
if times is not None:
warnings.warn('times keyword argument is deprecated and will be '
Expand Down
21 changes: 10 additions & 11 deletions pvlib/tracking.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,17 +305,16 @@ def singleaxis(apparent_zenith, apparent_azimuth,
Returns
-------
dict or DataFrame with the following columns:

* tracker_theta: The rotation angle of the tracker.
tracker_theta = 0 is horizontal, and positive rotation angles are
clockwise.
* aoi: The angle-of-incidence of direct irradiance onto the
rotated panel surface.
* surface_tilt: The angle between the panel surface and the earth
surface, accounting for panel rotation.
* surface_azimuth: The azimuth of the rotated panel, determined by
projecting the vector normal to the panel's surface to the earth's
surface.
* `tracker_theta`: The rotation angle of the tracker.
tracker_theta = 0 is horizontal, and positive rotation angles are
clockwise.
* `aoi`: The angle-of-incidence of direct irradiance onto the
rotated panel surface.
* `surface_tilt`: The angle between the panel surface and the earth
surface, accounting for panel rotation.
* `surface_azimuth`: The azimuth of the rotated panel, determined by
projecting the vector normal to the panel's surface to the earth's
surface.

References
----------
Expand Down