Widget documentation sweep

docs/api/placeholder.md

@@ -1 +1,2 @@
 ::: textual.widgets.Placeholder
+::: textual.widgets._placeholder.PlaceholderVariant

docs/api/tree.md

@@ -1 +1,4 @@
 ::: textual.widgets.Tree
+::: textual.widgets._tree.TreeNode
+::: textual.widgets._tree.NodeID
+::: textual.widgets._tree.TreeDataType

docs/api/welcome.md

@@ -0,0 +1 @@
+::: textual.widgets.Welcome

mkdocs-nav.yml

@@ -179,9 +179,9 @@ nav:
     - "api/text_log.md"
     - "api/toggle_button.md"
     - "api/timer.md"
-    - "api/tree_node.md"
     - "api/tree.md"
     - "api/walk.md"
+    - "api/welcome.md"
     - "api/widget.md"
   - "Blog":
     - blog/index.md

src/textual/widgets/_header.py

@@ -1,9 +1,12 @@
+"""Provides a Textual application header widget."""
+
 from __future__ import annotations
 
 from datetime import datetime
 
 from rich.text import Text
 
+from ..app import RenderResult
 from ..reactive import Reactive
 from ..widget import Widget
 
@@ -19,9 +22,16 @@ class HeaderIcon(Widget):
         content-align: left middle;
     }
     """
+
     icon = Reactive("⭘")
+    """The character to use as the icon within the header."""
+
+    def render(self) -> RenderResult:
+        """Render the header icon.
 
-    def render(self):
+        Returns:
+            The value to render.
+        """
         return self.icon
 
 
@@ -36,7 +46,12 @@ class HeaderClockSpace(Widget):
     }
     """
 
-    def render(self) -> str:
+    def render(self) -> RenderResult:
+        """Render the header clock space.
+
+        Returns:
+            The value to render.
+        """
         return ""
 
 
@@ -55,7 +70,12 @@ class HeaderClock(HeaderClockSpace):
     def on_mount(self) -> None:
         self.set_interval(1, callback=self.refresh, name=f"update header clock")
 
-    def render(self):
+    def render(self) -> RenderResult:
+        """Render the header clock.
+
+        Returns:
+            The value to render.
+        """
         return Text(datetime.now().time().strftime("%X"))
 
 
@@ -70,9 +90,17 @@ class HeaderTitle(Widget):
     """
 
     text: Reactive[str] = Reactive("")
+    """The main title text."""
+
     sub_text = Reactive("")
+    """The sub-title text."""
+
+    def render(self) -> RenderResult:
+        """Render the title and sub-title.
 
-    def render(self) -> Text:
+        Returns:
+            The value to render.
+        """
         text = Text(self.text, no_wrap=True, overflow="ellipsis")
         if self.sub_text:
             text.append(" — ")
@@ -81,11 +109,7 @@ def render(self) -> Text:
 
 
 class Header(Widget):
-    """A header widget with icon and clock.
-
-    Args:
-        show_clock: True if the clock should be shown on the right of the header.
-    """
+    """A header widget with icon and clock."""
 
     DEFAULT_CSS = """
     Header {
@@ -103,6 +127,7 @@ class Header(Widget):
     DEFAULT_CLASSES = ""
 
     tall = Reactive(False)
+    """Track if the `Header` is in a tall state or not."""
 
     def __init__(
         self,
@@ -112,13 +137,21 @@ def __init__(
         id: str | None = None,
         classes: str | None = None,
     ):
+        """Initialise the header widget.
+
+        Args:
+            show_clock: ``True`` if the clock should be shown on the right of the header.
+            name: The name of the header widget.
+            id: The ID of the header widget in the DOM.
+            classes: The CSS classes of the header widget.
+        """
         super().__init__(name=name, id=id, classes=classes)
-        self.show_clock = show_clock
+        self._show_clock = show_clock
 
     def compose(self):
         yield HeaderIcon()
         yield HeaderTitle()
-        yield HeaderClock() if self.show_clock else HeaderClockSpace()
+        yield HeaderClock() if self._show_clock else HeaderClockSpace()
 
     def watch_tall(self, tall: bool) -> None:
         self.set_class(tall, "-tall")

src/textual/widgets/_list_item.py

@@ -1,10 +1,19 @@
+"""Provides a list item widget for use with `ListView`."""
+
 from textual import events
 from textual.message import Message
 from textual.reactive import reactive
 from textual.widget import Widget
 
 
 class ListItem(Widget, can_focus=False):
+    """A widget that is an item within a `ListView`.
+
+    A `ListItem` is designed for use within a
+    [ListView][textual.widgets._list_view.ListView], please see `ListView`'s
+    documentation for more details on use.
+    """
+
     DEFAULT_CSS = """
     ListItem {
         color: $text;
@@ -27,12 +36,11 @@ class ListItem(Widget, can_focus=False):
     """
 
     highlighted = reactive(False)
+    """Is this item highlighted?"""
 
     class _ChildClicked(Message):
         """For informing with the parent ListView that we were clicked"""
 
-        pass
-
     def on_click(self, event: events.Click) -> None:
         self.post_message_no_wait(self._ChildClicked(self))
 

src/textual/widgets/_placeholder.py

@@ -1,3 +1,5 @@
+"""Provides a Textual placeholder widget; useful when designing an app's layout."""
+
 from __future__ import annotations
 
 from itertools import cycle
@@ -8,9 +10,11 @@
 from .. import events
 from ..css._error_tools import friendly_list
 from ..reactive import Reactive, reactive
-from ..widget import RenderResult, Widget
+from ..widget import Widget
 
 PlaceholderVariant = Literal["default", "size", "text"]
+"""The different variants of placeholder."""
+
 _VALID_PLACEHOLDER_VARIANTS_ORDERED: list[PlaceholderVariant] = [
     "default",
     "size",
@@ -94,14 +98,12 @@ def __init__(
 
         Args:
             label: The label to identify the placeholder.
-                If no label is present, uses the placeholder ID instead. Defaults to None.
+                If no label is present, uses the placeholder ID instead.
             variant: The variant of the placeholder.
-                Defaults to "default".
             name: The name of the placeholder. Defaults to None.
             id: The ID of the placeholder in the DOM.
-                Defaults to None.
             classes: A space separated string with the CSS classes
-                of the placeholder, if any. Defaults to None.
+                of the placeholder, if any.
         """
         # Create and cache renderables for all the variants.
         self._renderables = {
@@ -115,12 +117,19 @@ def __init__(
         self.styles.background = f"{next(Placeholder._COLORS)} 50%"
 
         self.variant = self.validate_variant(variant)
+        """The current variant of the placeholder."""
+
         # Set a cycle through the variants with the correct starting point.
         self._variants_cycle = cycle(_VALID_PLACEHOLDER_VARIANTS_ORDERED)
         while next(self._variants_cycle) != self.variant:
             pass
 
     def render(self) -> RenderableType:
+        """Render the placeholder.
+
+        Returns:
+            The value to render.
+        """
         return self._renderables[self.variant]
 
     def cycle_variant(self) -> None:

src/textual/widgets/_pretty.py

@@ -1,3 +1,5 @@
+"""Provides a pretty-printing widget."""
+
 from __future__ import annotations
 
 from typing import Any
@@ -8,6 +10,11 @@
 
 
 class Pretty(Widget):
+    """A pretty-printing widget.
+
+    Used to pretty-print any object.
+    """
+
     DEFAULT_CSS = """
     Static {
         height: auto;
@@ -22,6 +29,14 @@ def __init__(
         id: str | None = None,
         classes: str | None = None,
     ) -> None:
+        """Initialise the `Pretty` widget.
+
+        Args:
+            object: The object to pretty-print.
+            name: The name of the pretty widget.
+            id: The ID of the pretty in the DOM.
+            classes: The CSS classes of the pretty.
+        """
         super().__init__(
             name=name,
             id=id,
@@ -30,8 +45,18 @@ def __init__(
         self._renderable = PrettyRenderable(object)
 
     def render(self) -> PrettyRenderable:
+        """Render the pretty-printed object.
+
+        Returns:
+            The value to render.
+        """
         return self._renderable
 
     def update(self, object: Any) -> None:
+        """Update the content of the pretty widget.
+
+        Args:
+            object: The object to pretty-print.
+        """
         self._renderable = PrettyRenderable(object)
         self.refresh(layout=True)

src/textual/widgets/_text_log.py

@@ -1,14 +1,15 @@
+"""Provides a scrollable text-logging widget."""
+
 from __future__ import annotations
 
-from typing import cast
+from typing import Optional, cast
 
 from rich.console import RenderableType
 from rich.highlighter import ReprHighlighter
 from rich.measure import measure_renderables
 from rich.pretty import Pretty
 from rich.protocol import is_renderable
 from rich.segment import Segment
-from rich.style import Style
 from rich.text import Text
 
 from .._cache import LRUCache
@@ -19,6 +20,8 @@
 
 
 class TextLog(ScrollView, can_focus=True):
+    """A widget for logging text."""
+
     DEFAULT_CSS = """
     TextLog{
         background: $surface;
@@ -27,7 +30,7 @@ class TextLog(ScrollView, can_focus=True):
     }
     """
 
-    max_lines: var[int | None] = var(None)
+    max_lines: var[int | None] = var[Optional[int]](None)
     min_width: var[int] = var(78)
     wrap: var[bool] = var(False)
     highlight: var[bool] = var(False)
@@ -54,10 +57,10 @@ def __init__(
             wrap: Enable word wrapping (default is off).
             highlight: Automatically highlight content.
             markup: Apply Rich console markup.
-            name: The name of the button.
-            id: The ID of the button in the DOM.
-            classes: The CSS classes of the button.
-            disabled: Whether the button is disabled or not.
+            name: The name of the text log.
+            id: The ID of the text log in the DOM.
+            classes: The CSS classes of the text log.
+            disabled: Whether the text log is disabled or not.
         """
         super().__init__(name=name, id=id, classes=classes, disabled=disabled)
         self.max_lines = max_lines
@@ -91,9 +94,9 @@ def write(
 
         Args:
             content: Rich renderable (or text).
-            width: Width to render or None to use optimal width. Defaults to `None`.
-            expand: Enable expand to widget width, or False to use `width`. Defaults to `False`.
-            shrink: Enable shrinking of content to fit width. Defaults to `True`.
+            width: Width to render or ``None`` to use optimal width.
+            expand: Enable expand to widget width, or ``False`` to use `width`.
+            shrink: Enable shrinking of content to fit width.
         """
 
         renderable: RenderableType