Merge pull request #3751 from Textualize/documentation-fixes

Documentation fixes.

docs/api/containers.md

@@ -1 +1,3 @@
 ::: textual.containers
+
+::: textual.widgets.ContentSwitcher

docs/styles/layout.md

@@ -23,7 +23,7 @@ See the [layout](../guide/layout.md) guide for more information.
 ## Example
 
 Note how the `layout` style affects the arrangement of widgets in the example below.
-To learn more about the grid layout, you can see the [layout guide](../guide/layout.md) or the [grid reference](./grid.md).
+To learn more about the grid layout, you can see the [layout guide](../guide/layout.md) or the [grid reference](../grid.md).
 
 === "Output"
 

docs/widgets/toast.md

@@ -7,9 +7,7 @@ A widget which displays a notification message.
 - [ ] Focusable
 - [ ] Container
 
-Note that `Toast` isn't designed to be used directly in your applications,
-but it is instead used by [`notify`][textual.app.App.notify] to
-display a message when using Textual's built-in notification system.
+!!! warning "Note that `Toast` isn't designed to be used directly in your applications, but it is instead used by [`notify`][textual.app.App.notify] to display a message when using Textual's built-in notification system."
 
 ## Styling
 
@@ -94,7 +92,7 @@ The toast widget provides the following component classes:
 
 ---
 
-::: textual.widgets._toast
+::: textual.widgets._toast.Toast
     options:
       show_root_heading: true
       show_root_toc_entry: true

mkdocs-nav.yml

@@ -167,6 +167,7 @@ nav:
           - "widgets/tabbed_content.md"
           - "widgets/tabs.md"
           - "widgets/text_area.md"
+          - "widgets/toast.md"
           - "widgets/tree.md"
   - API:
       - "api/index.md"

src/textual/_system_commands.py

@@ -17,7 +17,7 @@ async def search(self, query: str) -> Hits:
         """Handle a request to search for system commands that match the query.
 
         Args:
-            user_input: The user input to be matched.
+            query: The user input to be matched.
 
         Yields:
             Command hits for use in the command palette.

src/textual/app.py

@@ -576,7 +576,7 @@ def validate_sub_title(self, sub_title: Any) -> str:
 
     @property
     def workers(self) -> WorkerManager:
-        """The [worker](guide/workers/) manager.
+        """The [worker](/guide/workers/) manager.
 
         Returns:
             An object to manage workers.
@@ -987,8 +987,8 @@ def _log(
     def call_from_thread(
         self,
         callback: Callable[..., CallThreadReturnType | Awaitable[CallThreadReturnType]],
-        *args: object,
-        **kwargs: object,
+        *args: Any,
+        **kwargs: Any,
     ) -> CallThreadReturnType:
         """Run a callable from another thread, and return the result.
 

src/textual/await_complete.py

@@ -16,9 +16,9 @@ def __init__(self, *coroutines: Coroutine[Any, Any, Any]) -> None:
         """Create an AwaitComplete.
 
         Args:
-            coroutine: One or more coroutines to execute.
+            coroutines: One or more coroutines to execute.
         """
-        self.coroutines = coroutines
+        self.coroutines: tuple[Coroutine[Any, Any, Any], ...] = coroutines
         self._future: Future = gather(*self.coroutines)
 
     async def __call__(self) -> Any:

src/textual/document/_syntax_aware_document.py

@@ -80,7 +80,7 @@ def prepare_query(self, query: str) -> Query | None:
         To execute a query, call `query_syntax_tree`.
 
         Args:
-            The string query to prepare.
+            query: The string query to prepare.
 
         Returns:
             The prepared query.

src/textual/dom.py

@@ -12,6 +12,7 @@
 from inspect import getfile
 from typing import (
     TYPE_CHECKING,
+    Any,
     Callable,
     ClassVar,
     Iterable,
@@ -1140,12 +1141,12 @@ def query_one(
 
         return query.only_one() if expect_type is None else query.only_one(expect_type)
 
-    def set_styles(self, css: str | None = None, **update_styles) -> Self:
+    def set_styles(self, css: str | None = None, **update_styles: Any) -> Self:
         """Set custom styles on this object.
 
         Args:
             css: Styles in CSS format.
-            **update_styles: Keyword arguments map style names on to style.
+            update_styles: Keyword arguments map style names onto style values.
 
         Returns:
             Self.

src/textual/fuzzy.py

@@ -1,7 +1,7 @@
 """
 Fuzzy matcher.
 
-This class is used by the [command palette](guide/command_palette) to match search terms.
+This class is used by the [command palette](/guide/command_palette) to match search terms.
 
 """
 

src/textual/widget.py

@@ -3244,18 +3244,18 @@ def release_mouse(self) -> None:
     def begin_capture_print(self, stdout: bool = True, stderr: bool = True) -> None:
         """Capture text from print statements (or writes to stdout / stderr).
 
-        If printing is captured, the widget will be sent an [events.Print][textual.events.Print] message.
+        If printing is captured, the widget will be sent an [`events.Print`][textual.events.Print] message.
 
-        Call [end_capture_print][textual.widget.Widget.end_capture_print] to disable print capture.
+        Call [`end_capture_print`][textual.widget.Widget.end_capture_print] to disable print capture.
 
         Args:
-            stdout: Capture stdout.
-            stderr: Capture stderr.
+            stdout: Whether to capture stdout.
+            stderr: Whether to capture stderr.
         """
         self.app.begin_capture_print(self, stdout=stdout, stderr=stderr)
 
     def end_capture_print(self) -> None:
-        """End print capture (set with [capture_print][textual.widget.Widget.capture_print])."""
+        """End print capture (set with [`begin_capture_print`][textual.widget.Widget.begin_capture_print])."""
         self.app.end_capture_print(self)
 
     def check_message_enabled(self, message: Message) -> bool:

src/textual/widgets/_data_table.py

@@ -2363,7 +2363,7 @@ def sort(
         Args:
             columns: One or more columns to sort by the values in.
             key: A function (or other callable) that returns a key to
-            use for sorting purposes.
+                use for sorting purposes.
             reverse: If True, the sort order will be reversed.
 
         Returns: