DOC/CLN: Fix cross-refs in docstrings, style. Fixes #239

Mostly fixing cross-refs in docstrings. Also makes some minor style/formatting fixes, e.g., ".txt file" -> "txt file", adds citations in a couple places. Add type hints in validation.py
vocalpy · Mar 21, 2023 · da6f385 · da6f385
1 parent 4af3a3c
commit da6f385
Show file tree

Hide file tree

Showing 19 changed files with 435 additions and 300 deletions.
diff --git a/src/crowsetta/annotation.py b/src/crowsetta/annotation.py
@@ -18,27 +18,28 @@ class Annotation:
     Attributes
     ----------
     annot_path : str, pathlib.Path
-        path to file from which annotations were loaded
+        Path to file from which annotations were loaded.
     notated_path : str, pathlib.Path
-        path to file that ``annot_path`` annotates.
+        Path to file that ``annot_path`` annotates.
         E.g., an audio file, or an array file
         that contains a spectrogram generated from audio.
         Optional, default is None.
     seq : crowsetta.Sequence
-        a sequence of annotated segments,
+        A sequence of annotated segments,
         each having an onset time, offset time,
-        and label.
+        and label. A :class:`crowsetta.Sequence` instance.
     bboxes : list
-        of ``crowsetta.BBox``,
-        annotated bounding boxes,
+        List of annotated bounding boxes,
         each having an onset time, offset time,
         lowest frequency, highest frequency,
         and label.
+        Each item in the list will be a
+        :class:`crowsetta.BBox` instance.
 
     Notes
     -----
-    A ``crowsetta.Annotation`` can have a ``seq``
-    or ``bboxes``, but not both.
+    A :class:`crowsetta.Annotation` can have either a ``seq``
+    attribute or a ``bboxes`` attribute, but not both.
 
     Examples
     --------

diff --git a/src/crowsetta/formats/__init__.py b/src/crowsetta/formats/__init__.py
@@ -16,6 +16,13 @@
                 FORMATS[attr.name] = attr
 
 
+__all__ = [
+    'bbox',
+    'FORMATS',
+    'seq'
+]
+
+
 def by_name(name: str) -> Type:
     """Get an annotation class by its string name
 
@@ -63,26 +70,27 @@ def as_list() -> list[str]:
 def register_format(format_class: Type) -> Type:
     """Decorator to register annotation formats.
 
-    Adds class to ``crowsetta.formats``.
+    Adds class to :mod:`crowsetta.formats`.
     The decorator maps the class variable ``name``,
     a string, to the class itself, so that calling
-    ``crowsetta.formats.by_name`` with that string
+    :func:`crowsetta.formats.by_name` with that string
     will return the class.
 
     Parameters
     ----------
     format_class : class
         A class that has the required class variables
         and adheres to one of the interfaces
-        defined in ``crowsetta.interface``,
-        either ``SeqLike`` or ``BBoxLike``.
+        defined in :mod:`crowsetta.interface`,
+        either :class:`~crowsetta.interface.seq.SeqLike`
+        or :class:`~crowsetta.interface.bbox.BBoxLike`.
 
     Returns
     -------
     format_class : class
         The same class, unchanged.
         This decorator only adds the class
-        to ``crowsetta.formats.FORMATS``.
+        to :data:`crowsetta.formats.FORMATS`.
     """
     if not issubclass(format_class, interface.seq.SeqLike) and not issubclass(format_class, interface.bbox.BBoxLike):
         raise TypeError(f"format class must be subclass of SeqLike or BBoxLike, but was not: {format_class}")

diff --git a/src/crowsetta/formats/bbox/audbbox.py b/src/crowsetta/formats/bbox/audbbox.py
@@ -1,5 +1,5 @@
 """Module for Audacity label tracks
-in extended format, exported to .txt files
+in extended format, exported to txt files
 https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
 """
 from __future__ import annotations
@@ -18,10 +18,10 @@
 
 def txt_to_records(aud_txt_path: PathLike) -> list[dict]:
     """Load a txt file in Audacity extended label track format
-    into records for a `pandas.DataFrame``.
+    into records for a :type:`pandas.DataFrame`.
 
-    Returns a ``list`` of ``dict`` that can be made into a
-    ``DataFrame`` by calling ``pandas.DataFrame.from_records``.
+    Returns a :class:`list` of :class:`dict` that can be made into a
+    :class:`~pandas.DataFrame` by calling :meth:`pandas.DataFrame.from_records`.
 
     Parameters
     ----------
@@ -30,13 +30,13 @@ def txt_to_records(aud_txt_path: PathLike) -> list[dict]:
     Returns
     -------
     records : list
-        Of ``dict``, each ``dict`` a row
-        in the ``DataFrame``.
+        Of :class:`dict`, each :class:`dict` will become
+        a row in the :class:`~pandas.DataFrame`.
 
     Notes
     -----
     We work with Audacity txt files this way, instead of
-    loading with ``pandas.read_csv`` then munging, so that we can
+    loading with :func:`pandas.read_csv` then munging, so that we can
     be sure that we can round-trip data without corrupting it.
     """
     with pathlib.Path(aud_txt_path).open("r") as fp:
@@ -58,29 +58,30 @@ def txt_to_records(aud_txt_path: PathLike) -> list[dict]:
 
 
 def df_to_lines(df: pd.DataFrame) -> list[str]:
-    """Convert a pandas DataFrame to a list of strings
-    that can be saved as a txt file in Audacity extended
+    """Convert a :type:`pandas.DataFrame` to a
+    :class:`list` of :class:`str` that can be saved
+    as a txt file in Audacity extended
     label track format.
 
     This function is (roughly) the inverse of
-    ``crowsetta.formats.bbox.audbbox.txt_to_records``.
+    :func:`crowsetta.formats.bbox.audbbox.txt_to_records`.
 
     Parameters
     ----------
     df : pandas.DataFrame
-        With contents of a .txt file in Audacity extended label track format,
-        after being loaded and parsed by ``crowsetta.formats.bbox.audbbox.audbbox_txt_to_df``
+        With contents of a txt file in Audacity extended label track format,
+        after being loaded and parsed by :func:`crowsetta.formats.bbox.audbbox.audbbox_txt_to_df`
 
     Returns
     -------
     lines : list
         List of strings that can be saved to a text file
-        by calling ``writelines``.
+        by calling :func:`writelines`.
 
     Notes
     -----
     We work with Audacity txt files this way, instead of
-    munging and then calling ``pandas.DataFrame.to_csv``,
+    munging and then calling :meth:`pandas.DataFrame.to_csv`,
     so that we can be sure that we can round-trip data
     without corrupting it.
     """
@@ -96,9 +97,10 @@ def df_to_lines(df: pd.DataFrame) -> list[str]:
 
 
 class AudBBoxSchema(pandera.SchemaModel):
-    """A ``pandera.SchemaModel`` that validates ``pandas`` dataframes
+    """A :class:`pandera.SchemaModel` that
+    validates :mod:`pandas` dataframes
     loaded from Audacity label tracks
-    in extended format, exported to .txt files
+    in extended format, exported to txt files
     https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
     """
 
@@ -117,7 +119,7 @@ class Config:
 @attr.define
 class AudBBox:
     """Class that represents Audacity label tracks
-    in extended format, exported to .txt files
+    in extended format, exported to txt files
     https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
 
     Attributes
@@ -129,9 +131,9 @@ class AudBBox:
     df : pandas.DataFrame
         with annotations loaded into it
     annot_path : str, pathlib.Path
-        Path to Audacity .txt file from which annotations were loaded.
+        Path to Audacity txt file from which annotations were loaded.
     audio_path : str. pathlib.Path
-        Path to audio file that the Audacity .txt file annotates.
+        Path to audio file that the Audacity txt file annotates.
     """
 
     COLUMNS_MAP: ClassVar[dict] = {
@@ -151,15 +153,15 @@ class AudBBox:
 
     @classmethod
     def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None) -> "Self":  # noqa: F821
-        """Load annotations from a Audacity annotation file with bbox,
+        """Load annotations from an Audacity annotation file with bounding boxes,
         created by exporting a Selection Table.
 
         Parameters
         ----------
         annot_path : str, pathlib.Path
-            Path to a .txt file exported from Audacity bbox.
+            Path to a txt file exported from Audacity bbox.
         audio_path : str, pathlib.Path
-            Path to audio file that the Audacity bbox .txt file annotates.
+            Path to audio file that the Audacity bbox txt file annotates.
             Optional, defaults to None.
 
         Examples
@@ -172,7 +174,7 @@ def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None)
         records = crowsetta.formats.bbox.audbbox.txt_to_records(annot_path)
         df = pd.DataFrame.from_records(records)
         if len(df) < 1:
-            raise ValueError(f"Cannot load annotations, " f"there are no rows in Audacity .txt file:\n{df}")
+            raise ValueError(f"Cannot load annotations, " f"there are no rows in Audacity txt file:\n{df}")
         df = crowsetta.formats.bbox.audbbox.AudBBoxSchema.validate(df)
 
         return cls(
@@ -182,12 +184,13 @@ def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None)
         )
 
     def to_bbox(self) -> List[crowsetta.BBox]:
-        """Convert this Audacity extended label track annotation to a ``list`` of ``crowsetta.Bbox``.
+        """Convert this Audacity extended label track annotation
+        to a :class:`list` of :class:`crowsetta.Bbox`.
 
         Returns
         -------
         bboxes : list
-            of ``crowsetta.BBox``
+            A :class:`list` of :class:`crowsetta.BBox` instances.
 
         Examples
         --------
@@ -209,7 +212,8 @@ def to_bbox(self) -> List[crowsetta.BBox]:
         return bboxes
 
     def to_annot(self) -> crowsetta.Annotation:
-        """Convert this Audacity bbox annotation to a ``crowsetta.Annotation``.
+        """Convert this Audacity bbox annotation
+        to a :class:`crowsetta.Annotation`.
 
         Returns
         -------
@@ -225,7 +229,7 @@ def to_annot(self) -> crowsetta.Annotation:
         return crowsetta.Annotation(annot_path=self.annot_path, notated_path=self.audio_path, bboxes=bboxes)
 
     def to_file(self, annot_path: PathLike) -> None:
-        """Make a .txt file from this annotation
+        """Make a txt file from this annotation
         in extended label track format that can be read by Audacity.
 
         Parameters

diff --git a/src/crowsetta/formats/bbox/raven.py b/src/crowsetta/formats/bbox/raven.py
@@ -18,8 +18,8 @@
 
 
 class RavenSchema(pandera.SchemaModel):
-    """A ``pandera.SchemaModel`` that validates ``pandas`` dataframes
-    loaded from a .txt file, created by exporting a Selection Table
+    """A :class:`pandera.SchemaModel` that validates :type:`pandas.DataFrame`s
+    loaded from a txt file, created by exporting a Selection Table
     from Raven.
     """
 
@@ -40,7 +40,7 @@ class Config:
 @crowsetta.interface.BBoxLike.register
 @attr.define
 class Raven:
-    """Class that represents .txt annotation files
+    """Class that represents txt annotation files
     from Raven (https://ravensoundsoftware.com/software/),
     created by exporting a Selection Table.
 
@@ -53,9 +53,9 @@ class Raven:
     df : pandas.DataFrame
         with annotations loaded into it
     annot_path : str, pathlib.Path
-        Path to Raven .txt file from which annotations were loaded.
+        Path to Raven txt file from which annotations were loaded.
     audio_path : str. pathlib.Path
-        Path to audio file that the Raven .txt file annotates.
+        Path to audio file that the Raven txt file annotates.
     """
 
     name: ClassVar[str] = "raven"
@@ -82,11 +82,11 @@ def from_file(
         Parameters
         ----------
         annot_path : str, pathlib.Path
-            Path to a .txt file exported from Raven.
+            Path to a txt file exported from Raven.
         annot_col : str
-            name of column that contains annotations
+            Name of column that contains annotations.
         audio_path : str, pathlib.Path
-            Path to audio file that the Raven .txt file annotates.
+            Path to audio file that the Raven txt file annotates.
             Optional, defaults to None.
 
         Examples
@@ -100,7 +100,7 @@ def from_file(
         #  assume file is space-separated with no header
         df = pd.read_csv(annot_path, sep="\t")
         if len(df) < 1:
-            raise ValueError(f"Cannot load annotations, " f"there are no rows in Raven .txt file:\n{df}")
+            raise ValueError(f"Cannot load annotations, " f"there are no rows in Raven txt file:\n{df}")
         columns_map = dict(cls.COLUMNS_MAP)  # copy
         columns_map.update({annot_col: "annotation"})
         df.rename(columns=columns_map, inplace=True)
@@ -114,12 +114,13 @@ def from_file(
         )
 
     def to_bbox(self) -> List[crowsetta.BBox]:
-        """Convert this Raven annotation to a ``list`` of ``crowsetta.Bbox``.
+        """Convert this Raven annotation to a
+        :class:`list` of :class:`crowsetta.Bbox` instances.
 
         Returns
         -------
         bboxes : list
-            of ``crowsetta.BBox``
+            A :class:`list` of :class:`crowsetta.BBox` instances.
 
         Examples
         --------
@@ -141,7 +142,8 @@ def to_bbox(self) -> List[crowsetta.BBox]:
         return bboxes
 
     def to_annot(self) -> crowsetta.Annotation:
-        """Convert this Raven annotation to a ``crowsetta.Annotation``.
+        """Convert this Raven annotation to a
+        :class:`crowsetta.Annotation`.
 
         Returns
         -------
@@ -157,13 +159,13 @@ def to_annot(self) -> crowsetta.Annotation:
         return crowsetta.Annotation(annot_path=self.annot_path, notated_path=self.audio_path, bboxes=bboxes)
 
     def to_file(self, annot_path: PathLike) -> None:
-        """make a .txt file that can be read by Raven
+        """Make a txt file that can be read by Raven
         from this annotation
 
         Parameters
         ----------
         annot_path : str, pahtlib.Path
-             path including filename where file should be saved.
+             Path including filename where file should be saved.
              Must have extension '.txt'
         """
         crowsetta.validation.validate_ext(annot_path, extension=self.ext)