Update docstrings to behave better with Sphinx

src/cladetime/cladetime.py

@@ -15,29 +15,40 @@
 
 
 class CladeTime:
-    """Wrapper around Nextstrain Sars-CoV-2 genome sequences, metadata, and clade assignments.
+    """Interface for Nextstrain Sars-CoV-2 genome sequences and clades.
 
-    The CladeTime class is instantiated with two optional arguments that
-    specify the point in time at which to access Nextstrain sequence
-    data and the reference tree used to assign sequences to clades.
+    The CladeTime class is instantiated with two optional arguments to
+    specify the point in time at which to access genome sequences/metadata
+    as well as the reference tree used for clade assignment.
 
     Parameters
     ----------
-    sequence_as_of : datetime
-        Use the NextStrain sequences and sequence metadata that were available
-        as of this date and time (UTC)
-    tree_as_of : datetime
-        Use the NextStrain reference tree that was available as of this date
-        and time (UTC)
+    sequence_as_of : datetime | str, optional
+        Sets the versions of Nextstrain SAR-CoV-2 genome sequence
+        and sequence metadata files that will be used by
+        CladeTime properties and methods. Can be a datetime object or a
+        string in YYYY-MM-DD format, both of which will be treated as
+        UTC. The default value is midnight of the current UTC date.
+    tree_as_of : datetime | str, optional
+        Sets the version of the Nextstrain reference tree that will be
+        used by CladeTime. Can be a datetime object or a string in
+        YYYY-MM-DD format, both of which will be treated as UTC.
+        The default value is :any:`sequence_as_ofa<sequence_as_of>`
 
     Attributes
     ----------
+    url_ncov_metadata : str
+        S3 URL to metadata from the Nextstrain pipeline run that
+        generated the sequence clade assignments in
+        :any:`url_sequence_metadata<url_sequence_metadata>`
     url_sequence : str
         S3 URL to the Nextstrain Sars-CoV-2 sequence file (zst-compressed
-        .fasta) that was available at the sequence_as_of
+        .fasta) that was current at the date specified in
+        :any:`sequence_as_of<sequence_as_of>`
     url_sequence_metadata : str
         S3 URL to the Nextstrain Sars-CoV-2 sequence metadata file
-        (zst-compressed tsv) that was available at the sequence_as_of
+        (zst-compressed tsv) that was current at the date specified in
+        :any:`sequence_as_of<sequence_as_of>`
     """
 
     def __init__(self, sequence_as_of=None, tree_as_of=None):
@@ -65,6 +76,12 @@ def __init__(self, sequence_as_of=None, tree_as_of=None):
 
     @property
     def sequence_as_of(self) -> datetime:
+        """
+        datetime.datetime : The date and time (UTC) used to retrieve NextStrain sequences
+        and sequence metadata. :any:`url_sequence<url_sequence>` and
+        :any:`url_sequence_metadata<url_sequence_metadata>` link to
+        Nextstrain files that were current as of this date.
+        """
         return self._sequence_as_of
 
     @sequence_as_of.setter
@@ -82,6 +99,12 @@ def sequence_as_of(self, date) -> None:
 
     @property
     def tree_as_of(self) -> datetime:
+        """
+        datetime.datetime : The date and time (UTC) used to retrieve the NextStrain
+        reference tree. :any:`get_reference_tree<get_reference_tree>`
+        uses this date to get the reference tree that was current as
+        of this date.
+        """
         return self._tree_as_of
 
     @tree_as_of.setter
@@ -106,9 +129,12 @@ def ncov_metadata(self):
 
     @ncov_metadata.getter
     def ncov_metadata(self) -> dict:
-        """dict : Metadata for the Nextstrain ncov pipeline that generated the
-        sequence and sequence metadata that correspond to the
-        sequence_as_of date"""
+        """
+        dict : Metadata for the reference tree that was used for SARS-CoV-2
+        clade assignments as of :any:`tree_as_ofa<tree_as_of>`.
+        This property will be empty for dates before 2024-08-01, when
+        Nextstrain began publishing ncov pipeline metadata.
+        """
         if self.url_ncov_metadata:
             metadata = _get_ncov_metadata(self.url_ncov_metadata)
             return metadata
@@ -122,7 +148,10 @@ def sequence_metadata(self):
 
     @sequence_metadata.getter
     def sequence_metadata(self) -> pl.LazyFrame:
-        """:class:`polars.LazyFrame` : A Polars LazyFrame that references :any:`the sequence metadata on S3<url_sequence_metadata>`"""
+        """
+        :class:`polars.LazyFrame` : A Polars LazyFrame that references
+        :any:`url_sequence_metadata<url_sequence_metadata>`
+        """
         if self.url_sequence_metadata:
             sequence_metadata = get_covid_genome_metadata(metadata_url=self.url_sequence_metadata)
             return sequence_metadata
@@ -164,3 +193,15 @@ def _validate_as_of_date(self, as_of: str) -> datetime:
             raise CladeTimeInvalidDateError(f"Date must be after May 1, 2023: {as_of_date}")
 
         return as_of_date
+
+    def get_reference_tree(self) -> dict:
+        """Return a reference tree used for SARS-CoV-2 clade assignments
+
+        Retrieves the reference tree that was current as of
+        :any:`tree_as_ofa<tree_as_of>`.
+
+        Returns
+        -------
+        dict
+        """
+        return {self.tree_as_of: "not implemented"}