From fddb6ebb08eae1e8f3fb6bcb8d54f506b7ce7aca Mon Sep 17 00:00:00 2001
From: Will McGugan <willmcgugan@gmail.com>
Date: Fri, 19 Jul 2024 12:19:46 +0100
Subject: [PATCH] docs

---
 docs/api/await_complete.md     |  3 ++-
 docs/api/await_remove.md       |  4 ++--
 docs/api/logger.md             |  8 ++------
 src/textual/__init__.py        | 27 +++++++++++++++++----------
 src/textual/binding.py         |  2 +-
 src/textual/cache.py           |  2 +-
 src/textual/command.py         |  3 ++-
 src/textual/constants.py       |  2 +-
 src/textual/css/query.py       |  2 ++
 src/textual/dom.py             |  3 ++-
 src/textual/lazy.py            |  1 -
 src/textual/pilot.py           |  2 +-
 src/textual/reactive.py        |  2 +-
 src/textual/screen.py          |  3 +++
 src/textual/scrollbar.py       |  7 +++++--
 src/textual/strip.py           |  4 +++-
 src/textual/suggester.py       |  2 +-
 src/textual/system_commands.py |  9 ++++++++-
 src/textual/timer.py           |  1 +
 src/textual/validation.py      |  8 +++++++-
 src/textual/widget.py          |  3 ++-
 src/textual/worker.py          |  5 ++++-
 src/textual/worker_manager.py  |  2 +-
 23 files changed, 69 insertions(+), 36 deletions(-)

diff --git a/docs/api/await_complete.md b/docs/api/await_complete.md
index 1782553bb4..74fd1759b8 100644
--- a/docs/api/await_complete.md
+++ b/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.
 
diff --git a/docs/api/await_remove.md b/docs/api/await_remove.md
index d13479a3f5..3543bce680 100644
--- a/docs/api/await_remove.md
+++ b/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.
 
diff --git a/docs/api/logger.md b/docs/api/logger.md
index 046af43498..2e47e4dfec 100644
--- a/docs/api/logger.md
+++ b/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
diff --git a/src/textual/__init__.py b/src/textual/__init__.py
index 64fa99601b..32cb3ad048 100644
--- a/src/textual/__init__.py
+++ b/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())
+    ```
+"""
diff --git a/src/textual/binding.py b/src/textual/binding.py
index 5ff189bb15..68f9bb6786 100644
--- a/src/textual/binding.py
+++ b/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.
 """
diff --git a/src/textual/cache.py b/src/textual/cache.py
index 85937b3449..66fcdb7eed 100644
--- a/src/textual/cache.py
+++ b/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.
 
 """
 
diff --git a/src/textual/command.py b/src/textual/command.py
index 10b1fbbcf6..63a88c9b4c 100644
--- a/src/textual/command.py
+++ b/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.
 
diff --git a/src/textual/constants.py b/src/textual/constants.py
index 9c420a7dc7..4730410e64 100644
--- a/src/textual/constants.py
+++ b/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."""
diff --git a/src/textual/css/query.py b/src/textual/css/query.py
index 6dec06f542..23233f8d2c 100644
--- a/src/textual/css/query.py
+++ b/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].
diff --git a/src/textual/dom.py b/src/textual/dom.py
index 1e9ea22570..656a005b3d 100644
--- a/src/textual/dom.py
+++ b/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
diff --git a/src/textual/lazy.py b/src/textual/lazy.py
index bbfe5762af..422a783d00 100644
--- a/src/textual/lazy.py
+++ b/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()
diff --git a/src/textual/pilot.py b/src/textual/pilot.py
index 739a66591e..036b18a6b3 100644
--- a/src/textual/pilot.py
+++ b/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).
 
diff --git a/src/textual/reactive.py b/src/textual/reactive.py
index 2507b14ab5..bb87ca9f0f 100644
--- a/src/textual/reactive.py
+++ b/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
diff --git a/src/textual/screen.py b/src/textual/screen.py
index 28168173ef..43750d5417 100644
--- a/src/textual/screen.py
+++ b/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
diff --git a/src/textual/scrollbar.py b/src/textual/scrollbar.py
index a105aa8370..069b33f6ab 100644
--- a/src/textual/scrollbar.py
+++ b/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
diff --git a/src/textual/strip.py b/src/textual/strip.py
index d3145e2753..b24733c1ad 100644
--- a/src/textual/strip.py
+++ b/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.
 """
 
diff --git a/src/textual/suggester.py b/src/textual/suggester.py
index 56e9cfad72..299b3d739d 100644
--- a/src/textual/suggester.py
+++ b/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.
 
 """
 
diff --git a/src/textual/system_commands.py b/src/textual/system_commands.py
index ffa73b263a..69cc17c953 100644
--- a/src/textual/system_commands.py
+++ b/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
diff --git a/src/textual/timer.py b/src/textual/timer.py
index 1cc8dcbdaa..d158962fd5 100644
--- a/src/textual/timer.py
+++ b/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].
 """
diff --git a/src/textual/validation.py b/src/textual/validation.py
index 4128c360d2..52a29c1396 100644
--- a/src/textual/validation.py
+++ b/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
 
diff --git a/src/textual/widget.py b/src/textual/widget.py
index b7296f6117..8c4f1598d5 100644
--- a/src/textual/widget.py
+++ b/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
diff --git a/src/textual/worker.py b/src/textual/worker.py
index d3455b9a61..9ad60a64ac 100644
--- a/src/textual/worker.py
+++ b/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
diff --git a/src/textual/worker_manager.py b/src/textual/worker_manager.py
index 6c90b9641a..ec0f8b4377 100644
--- a/src/textual/worker_manager.py
+++ b/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].
 """