Document widget style property access

changes/4353.doc.md

@@ -0,0 +1 @@
+The Widget reference now explains how style properties can be provided through a style object, constructor keyword arguments, or direct widget attributes.

core/src/toga/widgets/base.py

@@ -69,10 +69,17 @@ def __init__(
 
         This is an abstract base class; it cannot be instantiated.
 
+        Properties provided by the widget's style can also be passed as constructor
+        keyword arguments, or read and written directly on the widget. For example,
+        `widget.margin = 10` is equivalent to `widget.style.margin = 10`.
+        By default, the widget will use [Pack](/reference/api/style/pack.md),
+        style attributes, but Toga allows for other style representations.
+
         :param id: The ID for the widget.
         :param style: A style object. If no style is provided, a default style
             will be applied to the widget.
-        :param kwargs: Initial style properties.
+        :param kwargs: Initial style properties. These override any matching
+            properties on the `style` argument.
         """
         if style is None:
             style = Pack(**kwargs)

docs/en/reference/api/widgets/widget.md

@@ -4,12 +4,32 @@
 
 This class exists only for actual widgets to inherit from; it should not be be instantiated directly.
 
+Every widget has a `style` object that controls its layout and presentation. By default, this is a [`Pack`][toga.style.Pack] style. Style properties can be set in any of these equivalent ways:
+
+```python
+import toga
+from toga.style import Pack
+
+# Provide a style object.
+widget = toga.Label("Hello", style=Pack(margin=10))
+
+# Provide style properties as constructor keyword arguments.
+widget = toga.Label("Hello", margin=10)
+
+# Read or write a style property directly on the widget.
+widget.margin = 10
+assert widget.margin == widget.style.margin
+```
+
+When both a `style` object and style keyword arguments are provided, the keyword arguments override matching properties from the style object. See the [Pack reference][toga.style.Pack] for the available default style properties.
+
 ## Reference
 
 <!-- REMOVE WHEN RESOLVED -->
 <!-- rumdl-disable MD013 -->
 ::: toga.Widget
     options:
+        show_bases: false
         show_if_no_docstring: true
 <!-- rumdl-enable MD013 -->