Improve docstrings

radiotools/cleaning/clean.py

@@ -5,54 +5,55 @@
 
 
 class WSClean:
+    """Wrapper class for WSClean.
+
+    Parameters
+    ----------
+    ms : str or Path
+        Path to the measurement set.
+    clean_config : dict or str or Path
+        Either a dict containing the wsclean options or
+        a path to a toml file containing the options.
+        See note.
+    create_skymodel : bool, optional
+        Whether to create a skymodel before cleaning the image.
+        Default: False.
+    save_config : bool or str or Path, optional
+        If True, save the config to a file relative to the file
+        this class is called from. If given a path, the config
+        is saved to that location instead. Default: False.
+
+    Notes
+    -----
+    A valid config may look like the following:
+
+    >>> clean_config = {
+    >>>     'multiscale': True,
+    >>>     'mgain': 0.5,
+    >>>     'file_name': 'path/to/measurement_set',
+    >>>     'data_column': 'DATA',
+    >>>     'gain': 0.03,
+    >>>     'weight': 'briggs 0',
+    >>>     'mf_weighting': False,
+    >>>     'size': [1024, 1024],
+    >>>     'scale': '0.1masec',
+    >>>     'pol': 'I',
+    >>>     'niter': 5000000,
+    >>>     'auto_threshold': 0.5,
+    >>>     'auto_mask': 3,
+    >>>     'padding': 1.3,
+    >>>     'mem': 30,
+    >>>     'verbose': True,
+    >>> }
+    """
+
     def __init__(
         self,
         ms: str | Path,
         clean_config: dict | str | Path = None,
         create_skymodel: bool = False,
         save_config: bool | str | Path = False,
     ) -> None:
-        """Wrapper class for WSClean.
-
-        Parameters
-        ----------
-        ms : str or Path
-            Path to the measurement set.
-        clean_config : dict or str or Path
-            Either a dict containing the wsclean options or
-            a path to a toml file containing the options.
-            See note.
-        create_skymodel : bool, optional
-            Whether to create a skymodel before cleaning the image.
-            Default: False.
-        save_config : bool or str or Path, optional
-            If True, save the config to a file relative to the file
-            this class is called from. If given a path, the config
-            is saved to that location instead. Default: False.
-
-        Notes
-        -----
-        A valid config may look like the following:
-
-        >>> clean_config = {
-        >>>     'multiscale': True,
-        >>>     'mgain': 0.5,
-        >>>     'file_name': 'path/to/measurement_set',
-        >>>     'data_column': 'DATA',
-        >>>     'gain': 0.03,
-        >>>     'weight': 'briggs 0',
-        >>>     'mf_weighting': False,
-        >>>     'size': [1024, 1024],
-        >>>     'scale': '0.1masec',
-        >>>     'pol': 'I',
-        >>>     'niter': 5000000,
-        >>>     'auto_threshold': 0.5,
-        >>>     'auto_mask': 3,
-        >>>     'padding': 1.3,
-        >>>     'mem': 30,
-        >>>     'verbose': True,
-        >>> }
-        """
         if not isinstance(clean_config, (dict, str, Path)):
             raise ValueError(
                 "Please provide EITHER a dict object or a path"

radiotools/visibility/visibility.py

@@ -37,6 +37,23 @@
 class SourceVisibility:
     """Plots the source visibility for a given location
     and time range.
+
+    Parameters
+    ----------
+    target : tuple or str
+        Tuple of RA/Dec coordinates or string of valid
+        target name (ICRS).
+    date : str or list[str]
+        Date or start and end points of a range of dates.
+    location : str or astropy.coordinates.EarthLocation
+        Name of an existing array layout included in pyvisgen,
+        a location, or astropy `EarthLocation` object of an
+        observatory or telescope.
+    obs_length: float
+        Observation length in hours.
+    frame : str, optional, default='icrs'
+        Type of coordinate frame the source sky coordinates
+        should represent. Defaults to ICRS.
     """
 
     def __init__(
@@ -48,24 +65,6 @@ def __init__(
         frame="icrs",
         print_optimal_date: bool = False,
     ) -> None:
-        """
-        Parameters
-        ----------
-        target : tuple or str
-            Tuple of RA/Dec coordinates or string of valid
-            target name (ICRS).
-        date : str or list[str]
-            Date or start and end points of a range of dates.
-        location : str or astropy.coordinates.EarthLocation
-            Name of an existing array layout included in pyvisgen,
-            a location, or astropy `EarthLocation` object of an
-            observatory or telescope.
-        obs_length: float
-            Observation length in hours.
-        frame : str, optional, default='icrs'
-            Type of coordinate frame the source sky coordinates
-            should represent. Defaults to ICRS.
-        """
         if isinstance(target, tuple):
             self.ra = u.Quantity(target[0], unit=u.deg)
             self.dec = u.Quantity(target[1], unit=u.deg)
@@ -227,19 +226,21 @@ def _plot_config(self, ax) -> None:
     def plot(self, figsize: tuple[int, int] = (10, 5), colors: list = None) -> tuple:
         """Plots the visibility of the source at the given
         time range. Also plots the positions of the sun and moon
-        if set to `True`.
+        if set to ``True``.
 
         Parameters
         ----------
-        figsize : tuple[int, int], optional, default=(10,5)
+        figsize : tuple[int, int], optional
             Figure size. Width, height in inches.
+            Default: (10, 5)
         colors : list, optional
             List of colors. If nothing provided a default
-            list of colors is used.
+            list of colors is used. Default: None
 
         Returns
         -------
-        tuple : Figure and axis objects.
+        tuple
+            Figure and axis objects.
         """
         if colors is None:
             colors = iter(COLORS)
@@ -290,7 +291,21 @@ def _time_delta(self, r1, r2):
 
         return max(0, delta)
 
-    def get_optimal_date(self, print_result=False):
+    def get_optimal_date(self, print_result: bool = False) -> list:
+        """Computes the best date to observe the target source.
+        Returns a list of three :class:`~pandas.Timestamp` where the
+        first and last are the best date :math:`\pm` `obs_length / 2`.
+
+        Parameters
+        ----------
+        print_result : bool, optional
+            If `True`, also prints the result. Default: `False`
+
+        Returns
+        -------
+        result : list
+            List of :class:`~pandas.Timestamp`.
+        """
         times = dict()
         t_range = namedtuple("t_range", ["start", "end"])