document class methods using sphinx3 recursive doc (#1075)

* Recursive class methods

* Clean up docstring

* Bump sphinx version

* Update what's new

* Add brackets to reference numbers

* Fix bulleted list in docstring. Pin sphinx and rtd_theme versions.

* Fix lint error

Author: veronicaguo

docs/sphinx/source/_static/no_reference_superscript.css

@@ -0,0 +1,13 @@
+/* no reference superscript */
+.footnote-reference {
+    font-size: 100% !important;  /* default is 90% */
+    top: 0.0em !important;  /* default is -0.4em */
+}
+
+/* reference number in brackets */
+.footnote-reference::before {
+  content: '[';
+}
+.footnote-reference::after {
+  content: ']';
+}

docs/sphinx/source/_static/reference_format.css

@@ -5,12 +5,12 @@
 .. autoclass:: {{ objname }}
 
    {% block methods %}
-   .. automethod:: __init__
-
    {% if methods %}
    .. rubric:: Methods
 
    .. autosummary::
+      :toctree:
+      :recursive:
    {% for item in methods %}
       ~{{ name }}.{{ item }}
    {%- endfor %}

docs/sphinx/source/_templates/autosummary/class.rst

@@ -218,9 +218,10 @@
 # custom CSS workarounds
 def setup(app):
     # A workaround for the responsive tables always having annoying scrollbars.
-    app.add_stylesheet("no_scrollbars.css")
+    app.add_css_file("no_scrollbars.css")
     # Override footnote callout CSS to be normal text instead of superscript
-    app.add_stylesheet("no_reference_superscript.css")
+    # In-line links to references as numbers in brackets.
+    app.add_css_file("reference_format.css")
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/sphinx/source/conf.py

@@ -31,6 +31,8 @@ Testing
 
 Documentation
 ~~~~~~~~~~~~~
+* Update sphinx to 3.1.2 and use the ``recursive`` option in ``autosummary`` class template.
+  (:issue:`1055`, :pull:`1075`)
 * Add gallery example about backtracking on sloped terrain. (:pull:`1077`)
 
 Requirements
@@ -40,5 +42,6 @@ Requirements
 Contributors
 ~~~~~~~~~~~~
 * Kevin Anderson (:ghuser:`kanderso-nrel`)
+* Siyan (Veronica) Guo (:ghuser:`veronicaguo`)
 * Will Holmgren (:ghuser:`wholmgren`)
 * Cliff Hansen (:ghuser:`cwhanse`)

docs/sphinx/source/whatsnew/v0.8.1.rst

@@ -656,11 +656,12 @@ def first_solar_spectral_loss(self, pw, airmass_absolute):
         calculate the spectral loss modifier. The model coefficients are
         specific to the module's cell type, and are determined by searching
         for one of the following keys in self.module_parameters (in order):
-            'first_solar_spectral_coefficients' (user-supplied coefficients)
-            'Technology' - a string describing the cell type, can be read from
-            the CEC module parameter database
-            'Material' - a string describing the cell type, can be read from
-            the Sandia module database.
+
+        - 'first_solar_spectral_coefficients' (user-supplied coefficients)
+        - 'Technology' - a string describing the cell type, can be read from
+          the CEC module parameter database
+        - 'Material' - a string describing the cell type, can be read from
+          the Sandia module database.
 
         Parameters
         ----------
@@ -741,12 +742,6 @@ def singlediode(self, photocurrent, saturation_current,
                     ivcurve_pnts=None):
         """Wrapper around the :py:func:`pvlib.pvsystem.singlediode` function.
 
-        Parameters
-        ----------
-        See :py:func:`pvsystem.singlediode` for details
-
-        Returns
-        -------
         See :py:func:`pvsystem.singlediode` for details
         """
         return singlediode(photocurrent, saturation_current,
@@ -757,12 +752,6 @@ def i_from_v(self, resistance_shunt, resistance_series, nNsVth, voltage,
                  saturation_current, photocurrent):
         """Wrapper around the :py:func:`pvlib.pvsystem.i_from_v` function.
 
-        Parameters
-        ----------
-        See :py:func:`pvsystem.i_from_v` for details
-
-        Returns
-        -------
         See :py:func:`pvsystem.i_from_v` for details
         """
         return i_from_v(resistance_shunt, resistance_series, nNsVth, voltage,
@@ -773,12 +762,6 @@ def snlinverter(self, v_dc, p_dc):
         """Uses :py:func:`pvlib.inverter.sandia` to calculate AC power based on
         ``self.inverter_parameters`` and the input voltage and power.
 
-        Parameters
-        ----------
-        See :py:func:`pvlib.inverter.sandia` for details
-
-        Returns
-        -------
         See :py:func:`pvlib.inverter.sandia` for details
         """
         return inverter.sandia(v_dc, p_dc, self.inverter_parameters)
@@ -787,12 +770,6 @@ def adrinverter(self, v_dc, p_dc):
         """Uses :py:func:`pvlib.inverter.adr` to calculate AC power based on
         ``self.inverter_parameters`` and the input voltage and power.
 
-        Parameters
-        ----------
-        See :py:func:`pvlib.inverter.adr` for details
-
-        Returns
-        -------
         See :py:func:`pvlib.inverter.adr` for details
         """
         return inverter.adr(v_dc, p_dc, self.inverter_parameters)

pvlib/pvsystem.py

@@ -149,8 +149,8 @@ def get_aoi(self, surface_tilt, surface_azimuth, solar_zenith,
 
         For a given set of solar zenith and azimuth angles, the
         surface tilt and azimuth parameters are typically determined
-        by :py:method:`~SingleAxisTracker.singleaxis`. The
-        :py:method:`~SingleAxisTracker.singleaxis` method also returns
+        by :py:meth:`~SingleAxisTracker.singleaxis`. The
+        :py:meth:`~SingleAxisTracker.singleaxis` method also returns
         the angle of incidence, so this method is only needed
         if using a different tracking algorithm.
 

pvlib/tracking.py

@@ -48,9 +48,9 @@
     'optional': ['cython', 'ephem', 'netcdf4', 'nrel-pysam', 'numba',
                  'pvfactors', 'siphon', 'statsmodels', 'tables',
                  'cftime >= 1.1.1'],
-    'doc': ['ipython', 'matplotlib', 'sphinx == 1.8.5', 'sphinx_rtd_theme',
-            'sphinx-gallery', 'docutils == 0.15.2', 'pillow',
-            'netcdf4', 'siphon', 'tables'],
+    'doc': ['ipython', 'matplotlib', 'sphinx == 3.1.2',
+            'sphinx_rtd_theme==0.5.0', 'sphinx-gallery', 'docutils == 0.15.2',
+            'pillow', 'netcdf4', 'siphon', 'tables'],
     'test': TESTS_REQUIRE
 }
 EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), [])))