Initial work on adding toggle buttons to the documentation

This just gets the API docs into place, and tidies up some of the docstirngs.

docs/api/checkbox.md

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

docs/api/radiobutton.md

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

docs/api/radioset.md

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

docs/api/toggle_button.md

@@ -0,0 +1 @@
+::: textual.widgets._toggle_button.ToggleButton

mkdocs-nav.yml

@@ -141,6 +141,7 @@ nav:
     - "api/app.md"
     - "api/binding.md"
     - "api/button.md"
+    - "api/checkbox.md"
     - "api/color.md"
     - "api/containers.md"
     - "api/coordinate.md"
@@ -163,6 +164,8 @@ nav:
     - "api/pilot.md"
     - "api/placeholder.md"
     - "api/query.md"
+    - "api/radiobutton.md"
+    - "api/radioset.md"
     - "api/reactive.md"
     - "api/screen.md"
     - "api/scroll_view.md"
@@ -170,6 +173,7 @@ nav:
     - "api/strip.md"
     - "api/switch.md"
     - "api/text_log.md"
+    - "api/toggle_button.md"
     - "api/timer.md"
     - "api/tree_node.md"
     - "api/tree.md"

src/textual/widgets/_checkbox.py

@@ -7,7 +7,10 @@ class Checkbox(ToggleButton):
     """A check box widget that represents a boolean value."""
 
     class Changed(ToggleButton.Changed):
-        """Posted when the value of the checkbox changes."""
+        """Posted when the value of the checkbox changes.
+
+        This message can be handled using an `on_checkbox_changed` method.
+        """
 
         # https://github.com/Textualize/textual/issues/1814
         namespace = "checkbox"

src/textual/widgets/_radio_button.py

@@ -6,14 +6,18 @@ from ._toggle_button import ToggleButton
 class RadioButton(ToggleButton):
     """A radio button widget that represents a boolean value.
 
-    TODO: Mention that this is best used in a RadioSet (yet to be added).
+    Note:
+        A `RadioButton` is best used within a [RadioSet][textual.widgets.RadioSet].
     """
 
     BUTTON_INNER = "⏺"
     """The character used to for the inside of the button."""
 
     class Changed(ToggleButton.Changed):
-        """Posted when the value of the radio button changes."""
+        """Posted when the value of the radio button changes.
+
+        This message can be handled using an `on_radio_button_changed` method.
+        """
 
         # https://github.com/Textualize/textual/issues/1814
         namespace = "radio_button"

src/textual/widgets/_toggle_button.py

@@ -19,7 +19,13 @@ from ._static import Static
 
 
 class ToggleButton(Static, can_focus=True):
-    """Base toggle button widget."""
+    """Base toggle button widget.
+
+    Warning:
+        `ToggleButton` should be considered to be an internal class; it
+        exists to serve as the common core of [Checkbox][textual.widgets.Checkbox] and
+        [RadioButton][textual.widgets.RadioButton].
+    """
 
     BINDINGS: ClassVar[list[BindingType]] = [
         Binding("enter,space", "toggle", "Toggle", show=False),
@@ -27,7 +33,7 @@ class ToggleButton(Static, can_focus=True):
     """
     | Key(s) | Description |
     | :- | :- |
-    | enter,space | Toggle the value. |
+    | enter, space | Toggle the value. |
     """
 
     COMPONENT_CLASSES: ClassVar[set[str]] = {
@@ -197,11 +203,14 @@ class ToggleButton(Static, can_focus=True):
         self.value = not self.value
 
     def action_toggle(self) -> None:
-        """Toggle the value of the widget."""
+        """Toggle the value of the widget when called as an action.
+
+        This would normally be used for a keyboard binding.
+        """
         self.toggle()
 
     def on_click(self) -> None:
-        """Toggle the value of the widget."""
+        """Toggle the value of the widget when clicked with the mouse."""
         self.toggle()
 
     class Changed(Message, bubble=True):
@@ -221,6 +230,11 @@ class ToggleButton(Static, can_focus=True):
             """The value of the toggle button after the change."""
 
     def watch_value(self) -> None:
-        """React to the value being changed."""
+        """React to the value being changed.
+
+        When triggered, the CSS class `-on` is applied to the widget if
+        `value` has become `True`, or it is removed if it has become
+        `False`. Subsequently a related `Changed` event will be posted.
+        """
         self.set_class(self.value, "-on")
         self.post_message_no_wait(self.Changed(self, self.value))