docstrings

Author: willmcgugan

src/textual/color.py

@@ -1,10 +1,11 @@
 """
-This module contains a powerful Color class which Textual uses to expose colors.
+This module contains a powerful [Color][textual.color.Color] class which Textual uses to manipulate colors.
 
 ## Named colors
 
 The following named colors are used by the [parse][textual.color.Color.parse] method.
 
+
 ```{.rich columns="80" title="colors"}
 from textual._color_constants import COLOR_NAME_TO_RGB
 from textual.color import Color
@@ -41,8 +42,6 @@
 from rich.color import Color as RichColor
 from rich.color import ColorType
 from rich.color_triplet import ColorTriplet
-from rich.style import Style
-from rich.text import Text
 from typing_extensions import Final
 
 from textual.css.scalar import percentage_string_to_float
@@ -143,6 +142,22 @@ class Color(NamedTuple):
     Colors are stored as three values representing the degree of red, green, and blue in a color, and a
     fourth "alpha" value which defines where the color lies on a gradient of opaque to transparent.
 
+    Example:
+        ```python
+        >>> from textual.color import Color
+        >>> color = Color.parse("red")
+        >>> color
+        Color(255, 0, 0)
+        >>> color.darken(0.5)
+        Color(98, 0, 0)
+        >>> color + Color.parse("green")
+        Color(0, 128, 0)
+        >>> color_with_alpha = Color(100, 50, 25, 0.5)
+        >>> color_with_alpha
+        Color(100, 50, 25, a=0.5)
+        >>> color + color_with_alpha
+        Color(177, 25, 12)
+        ```
 
     """
 
@@ -185,7 +200,12 @@ def from_hsl(cls, h: float, s: float, l: float) -> Color:
 
     @property
     def inverse(self) -> Color:
-        """The inverse of this color."""
+        """The inverse of this color.
+
+        Returns:
+            Inverse color.
+
+        """
         r, g, b, a = self
         return Color(255 - r, 255 - g, 255 - b, a)
 
@@ -242,6 +262,9 @@ def hsl(self) -> HSL:
 
         HSL color is an alternative way of representing a color, which can be used in certain color calculations.
 
+        Returns:
+            Color encoded in HSL format.
+
         """
         r, g, b = self.normalized
         h, l, s = rgb_to_hls(r, g, b)
@@ -295,7 +318,12 @@ def css(self) -> str:
 
     @property
     def monochrome(self) -> Color:
-        """A monochrome version of this color."""
+        """A monochrome version of this color.
+
+        Returns:
+            The monochrome (black and white) version of this color.
+
+        """
         r, g, b, a = self
         gray = round(r * 0.2126 + g * 0.7152 + b * 0.0722)
         return Color(gray, gray, gray, a)

src/textual/geometry.py

@@ -61,6 +61,21 @@ class Offset(NamedTuple):
 
     Textual prefers the names `x` and `y`, but you could consider `x` to be the _column_ and `y` to be the _row_.
 
+    Offsets support addition, subtraction, multiplication, and negation.
+
+    Example:
+        ```python
+        >>> from textual.geometry import Offset
+        >>> offset = Offset(3, 2)
+        >>> offset
+        Offset(x=3, y=2)
+        >>> offset += Offset(10, 0)
+        >>> offset
+        Offset(x=13, y=2)
+        >>> -offset
+        Offset(x=-13, y=-2)
+        ```
+
     """
 
     x: int = 0
@@ -139,7 +154,21 @@ def get_distance_to(self, other: Offset) -> float:
 
 
 class Size(NamedTuple):
-    """The dimensions of a rectangular region."""
+    """The dimensions (width and height) of a rectangular region.
+
+    Example:
+        ```python
+        >>> from textual.geometry import Size
+        >>> size = Size(2, 3)
+        >>> size
+        Size(width=2, height=3)
+        >>> size.area
+        6
+        >>> size + Size(10, 20)
+        Size(width=12, height=23)
+        ```
+
+    """
 
     width: int = 0
     """The width in cells."""
@@ -237,6 +266,24 @@ class Region(NamedTuple):
         ◀─────── width ──────▶
     ```
 
+    Example:
+        ```python
+        >>> from textual.geometry import Region
+        >>> region = Region(4, 5, 20, 10)
+        >>> region
+        Region(x=4, y=5, width=20, height=10)
+        >>> region.area
+        200
+        >>> region.size
+        Size(width=20, height=10)
+        >>> region.offset
+        Offset(x=4, y=5)
+        >>> region.contains(1, 2)
+        False
+        >>> region.contains(10, 8)
+        True
+        ```
+
     """
 
     x: int = 0
@@ -831,7 +878,24 @@ def split_horizontal(self, cut: int) -> tuple[Region, Region]:
 
 
 class Spacing(NamedTuple):
-    """The spacing around a renderable."""
+    """The spacing around a renderable, such as padding and border
+
+    Spacing is defined by four integers for the space at the top, right, bottom, and left of a region,
+
+    Example:
+        ```python
+        >>> from textual.geometry import Region, Spacing
+        >>> region = Region(2, 3, 20, 10)
+        >>> spacing = Spacing(1, 2, 3, 4)
+        >>> region.grow(spacing)
+        Region(x=-2, y=2, width=26, height=14)
+        >>> region.shrink(spacing)
+        Region(x=6, y=4, width=14, height=6)
+        >>> spacing.css
+        '1 2 3 4'
+        ```
+
+    """
 
     top: int = 0
     """Space from the top of a region."""