chore: found a few docs rough edges

fgpyo/read_structure.py

@@ -15,7 +15,6 @@
 
 Examples
 ~~~~~~~~
-.. code-block:: python
 
    >>> from fgpyo.read_structure import ReadStructure
    >>> rs = ReadStructure.from_string("75T8B75T")
@@ -53,13 +52,14 @@
 The module contains the following public classes:
     - :class:`~fgpyo.read_structure.ReadStructure` -- Describes the structure of a give read
     - :class:`~fgpyo.read_structure.ReadSegment` -- Describes all the information about a segment
-        within a read structure
+      within a read structure
     - :class:`~fgpyo.read_structure.SegmentType` -- The type of segments that can show up in a read
-        structure
+      structure
     - :class:`~fgpyo.read_structure.SubReadWithoutQuals` -- Contains the bases that correspond to
-        the given read segment
+      the given read segment
     - :class:`~fgpyo.read_structure.SubReadWithQuals` -- Contains the bases and qualities that
-        correspond to the given read segment
+      correspond to the given read segment
+
 """
 import enum
 from typing import Iterable
@@ -70,32 +70,44 @@
 
 import attr
 
-# A character that can be put in place of a number in a read structure to mean "0 or more bases".
+
 ANY_LENGTH_CHAR: str = "+"
+"""A character that can be put in place of a number in a read structure to mean "0 or more bases"."""
 
 
 @enum.unique
 class SegmentType(enum.Enum):
     """The type of segments that can show up in a read structure"""
 
     Template = "T"
+    """The segment type for template bases."""
+
     SampleBarcode = "B"
+    """The segment type for sample barcode bases."""
+
     MolecularBarcode = "M"
+    """The segment type for molecular barcode bases."""
+
     Skip = "S"
+    """The segment type for bases that need to be skipped."""
 
     def __str__(self) -> str:
         return self.value
 
 
 @attr.s(frozen=True, auto_attribs=True, kw_only=True)
 class SubReadWithoutQuals:
-    """Contains the bases that correspond to the given read segment"""
+    """Contains the bases that correspond to the given read segment."""
 
     bases: str
+    """The sub-read bases that correspond to the given read segment."""
+
     segment: "ReadSegment"
+    """The segment of the read structure that describes this sub-read."""
 
     @property
     def kind(self) -> SegmentType:
+        """The kind of read segment that corresponds to this sub-read."""
         return self.segment.kind
 
 
@@ -104,11 +116,17 @@ class SubReadWithQuals:
     """Contains the bases and qualities that correspond to the given read segment"""
 
     bases: str
+    """The sub-read bases that correspond to the given read segment."""
+
     quals: str
+    """The sub-read base qualities that correspond to the given read segment."""
+
     segment: "ReadSegment"
+    """The segment of the read structure that describes this sub-read."""
 
     @property
     def kind(self) -> SegmentType:
+        """The kind of read segment that corresponds to this sub-read."""
         return self.segment.kind
 
 
@@ -119,9 +137,10 @@ class ReadSegment:
     (can be any length, 0 or more) in which case length must be None.
 
     Attributes:
-        offset: the offset of the read segment in the read
-        length: the length of the segment, or None if it is variable length
-        kind: the kind of read segment
+        offset: The offset of the read segment in the read.
+        length: The length of the segment, or None if it is variable length.
+        kind: The kind of read segment.
+
     """
 
     offset: int
@@ -190,7 +209,8 @@ class ReadStructure(Iterable[ReadSegment]):
     length and some offset from the start of the read.
 
     Attributes:
-         segments: the segments composing the read structure
+         segments: The segments composing the read structure
+
     """
 
     segments: Tuple[ReadSegment, ...]

fgpyo/util/metric.py

@@ -129,8 +129,8 @@ class Metric(ABC, Generic[MetricType]):
     makes it easy for them to be read in languages like `R`.
 
     Sub-classes of :class:`~fgpyo.util.metric.Metric` can support parsing and formatting custom
-    types with :func::`~fgpyo.util.metric.Metric._parsers` and
-    :func::`~fgpyo.util.metric.Metric.format_value`.
+    types with :func:`~fgpyo.util.metric.Metric._parsers` and
+    :func:`~fgpyo.util.metric.Metric.format_value`.
     """
 
     def values(self) -> Iterator[Any]:
@@ -219,7 +219,9 @@ def read(cls, path: Path, ignore_extra_fields: bool = True) -> Iterator[Any]:
     @classmethod
     def parse(cls, fields: List[str]) -> Any:
         """Parses the string-representation of this metric.  One string per attribute should be
-        given."""
+        given.
+
+        """
         parsers = cls._parsers()
         header = cls.header()
         assert len(fields) == len(header)
@@ -232,8 +234,9 @@ def write(cls, path: Path, *values: MetricType) -> None:
         The header will always be written.
 
         Args:
-            path: path to the output file
-            values: zero or more metrics.
+            path: Path to the output file.
+            values: Zero or more metrics.
+
         """
         with io.to_writer(path) as writer:
             writer.write("\t".join(cls.header()))