docs

docs/api/await_complete.md

@@ -2,7 +2,8 @@
 title: "textual.await_complete"
 ---
 
-This object is returned by methods that do work in the *background*.
+This module contains the `AwaitComplete` class.
+An `AwaitComplete` object is returned by methods that do work in the *background*.
 You can await this object if you need to know when that work has completed.
 Or you can ignore it, and Textual will automatically await the work before handling the next message.
 

docs/api/await_remove.md

@@ -2,8 +2,8 @@
 title: "textual.await_remove"
 ---
 
-
-This object is returned by [`Widget.remove()`][textual.widget.Widget.remove] and other methods which remove widgets.
+This module contains the `AwaitRemove` class.
+An `AwaitRemove` object is returned by [`Widget.remove()`][textual.widget.Widget.remove] and other methods which remove widgets.
 You can await the return value if you need to know exactly when the widget(s) have been removed.
 Or you can ignore it and Textual will wait for the widgets to be removed before handling the next message.
 

docs/api/logger.md

@@ -1,10 +1,6 @@
 ---
-title: "textual.Logger"
+title: "textual"
 ---
 
 
-# Logger
-
-A [logger class](/guide/devtools/#logging-handler) that logs to the Textual [console](/guide/devtools#console).
-
-::: textual.Logger
+::: textual

src/textual/__init__.py

@@ -1,10 +1,16 @@
+"""
+The root Textual module.
+
+Exposes some commonly used symbols.
+
+"""
+
 from __future__ import annotations
 
 import inspect
 from typing import TYPE_CHECKING, Callable
 
 import rich.repr
-from rich.console import RenderableType
 
 from . import constants
 from ._context import active_app
@@ -28,10 +34,10 @@
 
 
 if TYPE_CHECKING:
-
     from importlib.metadata import version
 
     __version__ = version("textual")
+    """The version of Textual."""
 
 else:
 
@@ -50,7 +56,7 @@ class LoggerError(Exception):
 
 @rich.repr.auto
 class Logger:
-    """A Textual logger."""
+    """A [logger class](/guide/devtools/#logging-handler) that logs to the Textual [console](/guide/devtools#console)."""
 
     def __init__(
         self,
@@ -165,10 +171,11 @@ def worker(self) -> Logger:
 
 
 log = Logger(None)
-
-
-def panic(*args: RenderableType) -> None:
-    from ._context import active_app
-
-    app = active_app.get()
-    app.panic(*args)
+"""Global logger that logs to the currently active app.
+
+Example:
+    ```python
+    from textual import log
+    log(locals())
+    ```
+"""

src/textual/binding.py

@@ -1,6 +1,6 @@
 """
 
-A binding maps a key press on to an action.
+This module contains the `Binding` class and related objects.
 
 See [bindings](/guide/input#bindings) in the guide for details.
 """

src/textual/cache.py

@@ -2,7 +2,7 @@
 
 Cache classes are dict-like containers used to avoid recalculating expensive operations such as rendering.
 
-You can also use them in your own apps if you need them.
+You can also use them in your own apps for similar reasons.
 
 """
 

src/textual/command.py

@@ -1,4 +1,5 @@
-"""The Textual command palette.
+"""
+This module contains classes for working with Textual's command palette.
 
 See the guide on the [Command Palette](../guide/command_palette.md) for full details.
 

src/textual/constants.py

@@ -111,7 +111,7 @@ def _get_textual_animations() -> AnimationLevel:
 """Maximum frames per second for updates."""
 
 COLOR_SYSTEM: Final[str | None] = get_environ("TEXTUAL_COLOR_SYSTEM", "auto")
-"""Force color system override"""
+"""Force color system override."""
 
 TEXTUAL_ANIMATIONS: AnimationLevel = _get_textual_animations()
 """Determines whether animations run or not."""

src/textual/css/query.py

@@ -1,4 +1,6 @@
 """
+This module contains the `DOMQuery` class and related objects.s
+
 A DOMQuery is a set of DOM nodes returned by [query][textual.dom.DOMNode.query].
 
 The set of nodes may be further refined with [filter][textual.css.query.DOMQuery.filter] and [exclude][textual.css.query.DOMQuery.exclude].

src/textual/dom.py

@@ -1,6 +1,7 @@
 """
-A DOMNode is a base class for any object within the Textual Document Object Model,
+The module contains `DOMNode`, the base class for any object within the Textual Document Object Model,
 which includes all Widgets, Screens, and Apps.
+
 """
 
 from __future__ import annotations

src/textual/lazy.py

@@ -21,7 +21,6 @@ class Lazy(Widget):
     in queries for a brief interval until they are mounted. Your code should take this in to account.
 
     Example:
-
         ```python
         def compose(self) -> ComposeResult:
             yield Footer()

src/textual/pilot.py

@@ -1,6 +1,6 @@
 """
 
-The pilot object is used by [App.run_test][textual.app.App.run_test] to programmatically operate an app.
+This module contains the `Pilot` class used by [App.run_test][textual.app.App.run_test] to programmatically operate an app.
 
 See the guide on how to [test Textual apps](/guide/testing).
 

src/textual/reactive.py

@@ -1,6 +1,6 @@
 """
 
-The `Reactive` class implements [reactivity](/guide/reactivity/).
+This module contains the `Reactive` class which implements [reactivity](/guide/reactivity/).
 """
 
 from __future__ import annotations

src/textual/screen.py

@@ -1,6 +1,9 @@
 """
 
+This module contains the `Screen` class and related objects.
+
 The `Screen` class is a special widget which represents the content in the terminal. See [Screens](/guide/screens/) for details.
+
 """
 
 from __future__ import annotations

src/textual/scrollbar.py

@@ -1,7 +1,10 @@
 """
-Implements the scrollbar-related widgets for internal use.
+Contains the widgets that manage Textual scrollbars.
+
+!!! note
+
+    You will not typically need this for most apps.
 
-You will not need to use the widgets defined in this module.
 """
 
 from __future__ import annotations

src/textual/strip.py

@@ -1,5 +1,7 @@
 """
-A Strip contains the result of rendering a widget.
+This module contains the `Strip` class and related objects.
+
+A `Strip` contains the result of rendering a widget.
 See [line API](/guide/widgets#line-api) for how to use Strips.
 """
 

src/textual/suggester.py

@@ -1,6 +1,6 @@
 """
 
-The `Suggester` class is used by the [Input](/widgets/input) widget.
+Contains the `Suggester` class, used by the [Input](/widgets/input) widget.
 
 """
 

src/textual/system_commands.py

@@ -1,7 +1,14 @@
-"""A command palette command provider for Textual system commands.
+"""
+
+This module contains `SystemCommands`, a command palette command provider for Textual system commands.
 
 This is a simple command provider that makes the most obvious application
 actions available via the [command palette][textual.command.CommandPalette].
+
+!!! note
+
+    The App base class installs this automatically.
+
 """
 
 from __future__ import annotations

src/textual/timer.py

@@ -1,5 +1,6 @@
 """
 
+Contains the `Timer` class.
 Timer objects are created by [set_interval][textual.message_pump.MessagePump.set_interval] or
     [set_timer][textual.message_pump.MessagePump.set_timer].
 """

src/textual/validation.py

@@ -1,4 +1,10 @@
-"""Framework for validating string values"""
+"""
+
+This module provides a number of classes for validating input.
+
+See [Validating Input](/widgets/input/#validating-input) for details.
+
+"""
 
 from __future__ import annotations
 

src/textual/widget.py

@@ -1,5 +1,6 @@
 """
-The base class for widgets.
+This module contains the `Widget` class, the base class for all widgets.
+
 """
 
 from __future__ import annotations

src/textual/worker.py

@@ -1,5 +1,8 @@
 """
-A class to manage concurrent [work](/guide/workers).
+This module contains the `Worker` class and related objects.
+
+See the guide for how to use [workers](/guide/workers).
+
 """
 
 from __future__ import annotations

src/textual/worker_manager.py

@@ -1,5 +1,5 @@
 """
-A class to manage [workers](/guide/workers) for an app.
+Contains `WorkerManager`, a class to manage [workers](/guide/workers) for an app.
 
 You access this object via [App.workers][textual.app.App.workers] or [Widget.workers][textual.dom.DOMNode.workers].
 """