improve localized classes documentation (#534)

Author: wholmgren

docs/sphinx/source/package_overview.rst

@@ -163,13 +163,15 @@ object describes the modeling chain used to calculate PV output at that
 Location. This can be a useful paradigm if you prefer to think about the
 PV system and its location as separate concepts or if you develop your
 own ModelChain subclasses. It can also be helpful if you make extensive
-use of Location-specific methods for other calculations.
+use of Location-specific methods for other calculations. pvlib-python
+also includes a :py:class:`~pvlib.tracking.SingleAxisTracker` class that
+is a subclass of :py:class:`~pvlib.pvsystem.PVSystem`.
 
 The following code demonstrates how to use
 :py:class:`~pvlib.location.Location`,
 :py:class:`~pvlib.pvsystem.PVSystem`, and
-:py:class:`~pvlib.modelchain.ModelChain`
-objects to accomplish our system modeling goal:
+:py:class:`~pvlib.modelchain.ModelChain` objects to accomplish our
+system modeling goal:
 
 .. ipython:: python
 
@@ -209,13 +211,30 @@ Object oriented (LocalizedPVSystem)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The second object oriented paradigm uses a model where a
-:py:class:`~pvlib.pvsystem.LocalizedPVSystem` represents a
-PV system at a particular place on the planet. This can be a useful
-paradigm if you're thinking about a power plant that already exists.
+:py:class:`~pvlib.pvsystem.LocalizedPVSystem` represents a PV system at
+a particular place on the planet. This can be a useful paradigm if
+you're thinking about a power plant that already exists.
+
+The :py:class:`~pvlib.pvsystem.LocalizedPVSystem` inherits from both
+:py:class:`~pvlib.pvsystem.PVSystem` and
+:py:class:`~pvlib.location.Location`, while the
+:py:class:`~pvlib.tracking.LocalizedSingleAxisTracker` inherits from
+:py:class:`~pvlib.tracking.SingleAxisTracker` (itself a subclass of
+:py:class:`~pvlib.pvsystem.PVSystem`) and
+:py:class:`~pvlib.location.Location`. The
+:py:class:`~pvlib.pvsystem.LocalizedPVSystem` and
+:py:class:`~pvlib.tracking.LocalizedSingleAxisTracker` classes may
+contain bugs due to the relative difficulty of implementing multiple
+inheritance. The :py:class:`~pvlib.pvsystem.LocalizedPVSystem` and
+:py:class:`~pvlib.tracking.LocalizedSingleAxisTracker` may be deprecated
+in a future release. We recommend that most modeling workflows implement
+:py:class:`~pvlib.location.Location`,
+:py:class:`~pvlib.pvsystem.PVSystem`, and
+:py:class:`~pvlib.modelchain.ModelChain`.
 
 The following code demonstrates how to use a
-:py:class:`~pvlib.pvsystem.LocalizedPVSystem`
-object to accomplish our modeling goal:
+:py:class:`~pvlib.pvsystem.LocalizedPVSystem` object to accomplish our
+modeling goal:
 
 .. ipython:: python
 

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

@@ -120,7 +120,8 @@ Documentation
 * Expanded general contributing and pull request guidelines.
 * Added section on single diode equation with some detail on solutions used in
   pvlib-python (:issue:`518`)
-
+* Improve LocalizedPVSystem and LocalizedSingleAxisTracker documentation.
+  (:issue:`532`)
 
 Testing
 ~~~~~~~

pvlib/pvsystem.py

@@ -690,8 +690,10 @@ class LocalizedPVSystem(PVSystem, Location):
     system attributes and modeling functions. This class combines the
     attributes and methods of the PVSystem and Location classes.
 
-    See the :py:class:`PVSystem` class for an object model that
-    describes an unlocalized PV system.
+    The LocalizedPVSystem may have bugs due to the difficulty of
+    robustly implementing multiple inheritance. See
+    :py:class:`~pvlib.modelchain.ModelChain` for an alternative paradigm
+    for modeling PV systems at specific locations.
     """
     def __init__(self, pvsystem=None, location=None, **kwargs):
 

pvlib/tracking.py

@@ -141,7 +141,7 @@ def get_irradiance(self, surface_tilt, surface_azimuth,
 
         For a given set of solar zenith and azimuth angles, the
         surface tilt and azimuth parameters are typically determined
-        by :py:method:`~SingleAxisTracker.singleaxis`.
+        by :py:meth:`~SingleAxisTracker.singleaxis`.
 
         Parameters
         ----------
@@ -195,7 +195,17 @@ def get_irradiance(self, surface_tilt, surface_azimuth,
 
 
 class LocalizedSingleAxisTracker(SingleAxisTracker, Location):
-    """Highly experimental."""
+    """
+    The LocalizedSingleAxisTracker class defines a standard set of
+    installed PV system attributes and modeling functions. This class
+    combines the attributes and methods of the SingleAxisTracker (a
+    subclass of PVSystem) and Location classes.
+
+    The LocalizedSingleAxisTracker may have bugs due to the difficulty
+    of robustly implementing multiple inheritance. See
+    :py:class:`~pvlib.modelchain.ModelChain` for an alternative paradigm
+    for modeling PV systems at specific locations.
+    """
 
     def __init__(self, pvsystem=None, location=None, **kwargs):