more docstrings

rubin_scheduler/scheduler/detailers/detailer.py

@@ -73,7 +73,8 @@ def __call__(self, observation_list, conditions):
 
 
 class FlushByDetailer(BaseDetailer):
-    """
+    """Set the MJD an observation should be flushed from the scheduler queue if not yet completed.
+
     Parameters
     ----------
     flush_time : float

rubin_scheduler/scheduler/surveys/pointings_survey.py

@@ -19,7 +19,7 @@ class PointingsSurvey(BaseSurvey):
 
     Parameters
     ----------
-    observations : np.array
+    observations : `np.array`
         An array of observations, from e.g. rubin_scheduler.scheduler.utils.empty_observation
         expect "RA", "dec", and "note" to be filled, other columns ignored.
     gap_min : `float`
@@ -28,23 +28,23 @@ class PointingsSurvey(BaseSurvey):
         Altitude limit of the telescope (degrees). Default 20.
     alt_max : `float`
         Altitude limit of the telescope (degrees). Default 85.
-    ha_max, ha_min : float (4,-4)
+    ha_max, ha_min : `float` (4,-4)
         hour angle limits (hours). Applied to all observations. Default 4,-4.
-    weights : dict
+    weights : `dict`
         Dictionary with keys of method names and values of floats.
         Default of None uses {"visit_gap": 1.0, "balance_revisit": 1.0,
                               "m5diff": 1.0,
                               "wind_limit": 1.0, "slew_time": -1.0,
                               "ha_limit": 0, "alt_limit": 0, "moon_limit": 0}
-    wind_speed_maximum : float
+    wind_speed_maximum : `float`
         The maximum wind (m/s), mask any targets that would take more wind than that.
         Default 100 m/s.
-    fiducial_FWHMEff : float
+    fiducial_FWHMEff : `float`
         A fiducial seeing value to use when computing dark sky depth.
         Default 0.7 arcsec.
-    sun_alt_limit : float
+    sun_alt_limit : `float`
         Have survey as infeasible when sun altitude is above the limit. default -12 (degrees).
-    track_notes_ngoal : dict
+    track_notes_ngoal : `dict`
         If there are observations that should be tracked together (e.g., a sequence that
         should be observed together). Dict with keys of str and values of int.
     """
@@ -130,6 +130,7 @@ def __init__(
             self.detailers = detailers
 
     def _check_feasibility(self, conditions):
+        """Check if the survey is feasable in the current conditions"""
         # Simple feasability check.
         result = True
 
@@ -143,6 +144,7 @@ def _check_feasibility(self, conditions):
         return result
 
     def calc_reward_function(self, conditions):
+        """Compute reward function using methods set by `weights` dict on init."""
         if self.last_computed_reward != conditions.mjd:
             self.alt, self.az = _approx_ra_dec2_alt_az(
                 self.observations["RA"],
@@ -167,13 +169,17 @@ def calc_reward_function(self, conditions):
         return np.nanmax(self.reward)
 
     def generate_observations_rough(self, conditions):
+        """Calculate reward function and highest reward observation. This is usually
+        called by `generate_observations` which will take the result and then apply detailers to them.
+        """
         max_reward = self.calc_reward_function(conditions)
         # take the first one in the array if there's a tie
         # Could change logic to return multiple pointings
         winner = np.min(np.where(self.reward == max_reward)[0])
         return [self.observations[winner].copy().reshape(1)]
 
     def add_observation(self, observation, indx=None):
+        """Let survey know about a completed observation."""
         # Check for a nore match
         indx = np.where(observation["note"] == self.observations["note"])[0]
         # Tracking arrays
@@ -186,6 +192,7 @@ def add_observation(self, observation, indx=None):
                 self.tracking_notes[key] += 1
 
     def add_observations_array(self, observations_array_in, observations_hpid_in):
+        """Like `add_observation`, but for a large array of completed observations."""
         for unote in np.unique(observations_array_in["note"]):
             matching = np.where(observations_array_in["note"] == unote)[0]
             indx = np.where(self.observations["note"] == unote)[0]

rubin_scheduler/skybrightness_pre/dark_sky.py

@@ -40,7 +40,25 @@ def dark_sky(nside=32):
 
 
 def dark_m5(decs, filtername, latitude_rad, fiducial_FWHMEff, exptime=30.0, nexp=1):
-    """Return a nominal best-depth map of the sky"""
+    """Return a nominal best-depth map of the sky
+
+    Parameters
+    ----------
+    decs : `float`
+        The declinations for the desired points. Float or adday-like. (radians)
+    filtername : `str`
+        Name of filter, one of ugrizy.
+    latitude_rad : `float`
+        Latitude of the observatory (radians)
+    fiducial_FWHMEff : `float`
+        The fiducial seeing FWHMeff to use (arcsec).
+    exptime : `float`
+        The fiducial exposure time to assume (seconds). Default 30.
+    nexp : `int`
+        The number of exposures per visit. Default 1.
+
+
+    """
     nside = hp.npix2nside(np.size(decs))
     ds = dark_sky(nside)[filtername]
     min_z = np.abs(decs - latitude_rad)