Update cross-references in docstrings

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: docs
+
+on:
+  workflow_dispatch:    # Allow manual trigger from the GitHub Actions UI
+
+jobs:
+  deploy:
+    name: Build Documentation
+    runs-on: macos-latest
+    defaults:
+      run:
+        working-directory: sdk/python/
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build docs
+        run: |
+          uv venv
+          uv pip install -e .
+          uv run --group docs --directory packages/flet mkdocs build -v

.github/workflows/macos-integration-tests.yml

@@ -14,6 +14,8 @@ on:
       - 'packages/flet/**'
       - 'client/**'
 
+  workflow_dispatch:
+
 # Ensure only one run per branch (PR or push), cancel older ones
 concurrency:
   group: macos-integration-tests-${{ github.workflow }}-${{ github.event.pull_request.head.ref || github.ref_name }}

packages/flet/pubspec.yaml

@@ -26,7 +26,7 @@ dependencies:
   provider: ^6.1.2
   web_socket_channel: ^3.0.2
   msgpack_dart: ^1.0.1
-  window_manager: ^0.5.0
+  window_manager: ^0.5.1
   window_to_front: ^0.0.3
   collection: ^1.19.0
   flutter_svg: 2.1.0
@@ -40,10 +40,10 @@ dependencies:
   markdown: 7.3.0
   sensors_plus: ^6.1.1
   web: ^1.1.1
-  file_picker: ^10.1.9
+  file_picker: ^10.3.3
   path_provider: ^2.1.5
   screenshot: ^3.0.0
-  
+
 dev_dependencies:
   flutter_test:
     sdk: flutter

sdk/python/packages/flet/docs/docs-style-guide.md → sdk/python/packages/flet/docs/contributing/docs.md

@@ -1,14 +1,16 @@
-# Docs Guide
+# Contributing Documentation
 
 We make use of [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/), [mkdocstrings-python](https://mkdocstrings.github.io/python/) and their extensions.
 
 ## Docstring Style
 
-We use the google style for documentation. More info and examples [here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+We use the google style for documentation.
+More info and examples [here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
 
 ## Cross References
 
-The class must be present in our topmost `__init__.py`, and can then be (cross-)referenced from anywhere as follows:
+Typically, the class to be cross-referenced must be present/exposed in the topmost
+`__init__.py`, and can then be (cross-)referenced from anywhere as follows:
 ```
 [`Row`][flet.Row]
 [`Row.controls`][flet.Row.controls]
@@ -31,9 +33,9 @@ Message.
 ```
 
 `type` can be: 'note' (default), 'attention', 'caution', 'danger', 'error', 'tip', 'hint', 'warning'
- ([Visual example](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types))
+([Visual example](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types))
 
- ### Method 2
+### Method 2
 
 [Docs](https://mkdocstrings.github.io/griffe/reference/docstrings/#google-syntax)
 

sdk/python/packages/flet/mkdocs.yml

@@ -108,7 +108,6 @@ plugins:
       alias_type: symlink
   - glightbox:
       background: none
-  # - section-index
   - markdown-exec
   - mkdocstrings:
       default_handler: python_xref

sdk/python/packages/flet/pyproject.toml

@@ -42,22 +42,24 @@ dev = [
     "pre-commit >=2.21.0",
     "pypi-cleanup==0.1.4",
     "pandas >=2.2.3",
-    "ruff>=0.11.7",
+    "numpy >=2.2.0",
+    "scikit-image >=0.25.2",
+    "ruff >=0.13.1",
     { include-group = 'test' },
 ]
 docs-coverage = [
     "docstr-coverage >=2.3.2",
 ]
 docs = [
     "mkdocs >=1.6.1",
-    "mkdocs-material >=9.6.15",
-    "mkdocstrings-python >=1.16.12",
-    "mkdocstrings-python-xref >=1.16.3",
+    "mkdocs-material >=9.6.20",
+    "mkdocstrings-python >=1.18.2",
+    "mkdocstrings-python-xref >=1.16.4",
     "mike >=2.1.3",
-    "markdown >=3.6",
-    "pymdown-extensions >=10.16",
+    "markdown >=3.9",
+    "pymdown-extensions >=10.16.1",
     "mkdocs-exclude >=1.0.2",
-    "mkdocs-glightbox >=0.4.0",
+    "mkdocs-glightbox >=0.5.1",
     "mkdocs-open-in-new-tab >=1.0.8",
     "mkdocs-section-index >=0.3.10",
     "griffe-modernized-annotations >=1.0.8",

sdk/python/packages/flet/src/flet/controls/adaptive_control.py

@@ -10,29 +10,32 @@
 class AdaptiveControl(Control):
     """
     Base class for controls that support adaptive behavior, which allows them to adjust
-    their appearance and behavior based on the target platform (ex: Material design on Android/Windows/Linux,
-    Cupertino design on iOS/macOS).
+    their appearance and behavior based on the target platform
+    (ex: Material design on Android/Windows/Linux, Cupertino design on iOS/macOS).
 
     The [`adaptive`][(c).] property is applicable in two common scenarios:
 
     1. **Platform-adaptive controls**:
-       These controls have a corresponding version on both Material and Cupertino platforms.
-       When `adaptive` is set to `True`, the control renders the appropriate platform-specific
-       implementation.
+        These controls have a corresponding version on both Material and Cupertino
+        platforms. When `adaptive` is set to `True`, the control renders the
+        appropriate platform-specific implementation.
 
     2. **Container controls**:
-       Controls that contain children (ex: [`Row`][flet.Row], [`Column`][flet.Column]) can pass
-       the `adaptive` value down to their children that do not explicitly define it themselves.
-       This enables nested adaptive behavior in complex layouts.
+        Controls that contain children (ex: [`Row`][flet.], [`Column`][flet.]) can pass
+        the `adaptive` value down to their children that do not explicitly define it
+        themselves. This enables nested adaptive behavior in complex layouts.
 
-    Extension developers can use this base class to create their own adaptive controls by
-    checking the `adaptive` flag at runtime and rendering accordingly.
+    Extension developers can use this base class to create their own adaptive controls
+    by checking the `adaptive` flag at runtime and rendering accordingly.
 
     Note:
         This class does not implement any platform-specific rendering itself.
-        It is up to the control inheriting from it to interpret the [`adaptive`][(c).] flag and render accordingly.
+        It is up to the control inheriting from it to interpret the [`adaptive`][(c).]
+        flag and render accordingly.
     """
+
     adaptive: Optional[bool] = None
     """
-    Enables platform-specific rendering or inheritance of adaptiveness from parent controls.
-    """
+    Enables platform-specific rendering or inheritance of adaptiveness
+    from parent controls.
+    """

sdk/python/packages/flet/src/flet/controls/base_page.py

@@ -167,8 +167,8 @@ class BasePage(AdaptiveControl):
         - This property is read-only.
         - To get or set the full window height including window chrome (e.g.,
             title bar and borders) when running a Flet app on desktop,
-            use the [`width`][flet.Window.width] property of
-            [`Page.window`][flet.Page.window] instead.
+            use the [`width`][flet.Window.] property of
+            [`Page.window`][flet.] instead.
     """
 
     height: Optional[Number] = None
@@ -179,8 +179,8 @@ class BasePage(AdaptiveControl):
         - This property is read-only.
         - To get or set the full window height including window chrome (e.g.,
             title bar and borders) when running a Flet app on desktop,
-            use the [`height`][flet.Window.height] property of
-            [`Page.window`][flet.Page.window] instead.
+            use the [`height`][flet.Window.] property of
+            [`Page.window`][flet.] instead.
     """
 
     title: Optional[str] = None
@@ -306,7 +306,7 @@ def show_dialog(self, dialog: DialogControl) -> None:
         This method adds the specified `dialog` to the active dialog stack
         and renders it on the page. If the dialog is already open, an exception
         is raised.
-        The [`on_dismiss`][flet.DialogControl.on_dismiss] handler of the dialog
+        The [`on_dismiss`][flet.DialogControl.] handler of the dialog
         is temporarily wrapped to ensure the dialog is removed from the stack and
         its dismissal event is triggered appropriately.
 

sdk/python/packages/flet/src/flet/controls/border.py

@@ -66,8 +66,9 @@ class BorderSide:
     This means that it will render faster than otherwise, but it might
     double-hit pixels, giving it a slightly darker/lighter result.
 
-    To omit the border entirely, set the [`style`][flet.BorderSide.style]
-    to [`BorderStyle.NONE`][flet.BorderStyle.NONE].
+    Tip:
+        To omit the border entirely, set the [`style`][(c).]
+        to [`BorderStyle.NONE`][flet.].
     """
 
     color: ColorValue = Colors.BLACK
@@ -161,7 +162,7 @@ class Border:
     A border comprised of four sides: `top`, `right`, `bottom`, `left`.
 
     Each side of the border is an instance of
-    [`BorderSide`][flet.BorderSide].
+    [`BorderSide`][flet.].
 
     Example:
         ```python

sdk/python/packages/flet/src/flet/controls/box.py

@@ -300,15 +300,13 @@ class BoxDecoration:
 
     image: Optional[DecorationImage] = None
     """
-    An image to paint above the background [`bgcolor`][flet.BoxDecoration.bgcolor]
-    or [`gradient`][flet.BoxDecoration.gradient].
+    An image to paint above the background [`bgcolor`][(c).] or [`gradient`][(c).].
     """
 
     border: Optional[Border] = None
     """
-    A border to draw above the background
-    [`bgcolor`][flet.BoxDecoration.bgcolor], [`gradient`][flet.BoxDecoration.gradient],
-    and [`image`][flet.BoxDecoration.image].
+    A border to draw above the background [`bgcolor`][(c).], [`gradient`][(c).],
+    and [`image`][(c).].
     """
 
     border_radius: Optional[BorderRadiusValue] = None
@@ -328,16 +326,13 @@ class BoxDecoration:
 
     shape: BoxShape = BoxShape.RECTANGLE
     """
-    The shape to fill the [`bgcolor`][flet.BoxDecoration.bgcolor],
-    [`gradient`][flet.BoxDecoration.gradient], and [`image`][
-    flet.BoxDecoration.image] into and to cast as the
-    [`shadows`][flet.BoxDecoration.shadows].
+    The shape to fill the [`bgcolor`][(c).], [`gradient`][(c).], and [`image`][(c).]
+    into and to cast as the [`shadows`][(c).].
     """
 
     blend_mode: Optional[BlendMode] = None
     """
-    The blend mode to apply to the background [`bgcolor`][flet.BoxDecoration.bgcolor]
-    or [`gradient`][flet.BoxDecoration.gradient].
+    The blend mode to apply to the background [`bgcolor`][(c).] or [`gradient`][(c).].
     """
 
     def __post_init__(self):

sdk/python/packages/flet/src/flet/controls/buttons.py

@@ -34,7 +34,7 @@ class ShapeBorder:
 
     See subclasses/implementations:
 
-    - [`OutlinedBorder`][flet.OutlinedBorder]
+    - [`OutlinedBorder`][flet.]
     """
 
 
@@ -45,11 +45,11 @@ class OutlinedBorder(ShapeBorder):
 
     See subclasses/implementations:
 
-    - [`BeveledRectangleBorder`][flet.BeveledRectangleBorder]
-    - [`ContinuousRectangleBorder`][flet.ContinuousRectangleBorder]
-    - [`CircleBorder`][flet.CircleBorder]
-    - [`RoundedRectangleBorder`][flet.RoundedRectangleBorder]
-    - [`StadiumBorder`][flet.StadiumBorder]
+    - [`BeveledRectangleBorder`][flet.]
+    - [`ContinuousRectangleBorder`][flet.]
+    - [`CircleBorder`][flet.]
+    - [`RoundedRectangleBorder`][flet.]
+    - [`StadiumBorder`][flet.]
     """
 
     side: Optional[BorderSide] = None
@@ -194,7 +194,7 @@ class ButtonStyle:
     background and shadow colors, content padding, border width and radius.
 
     Most of these style attributes could be configured for all or particular
-    [`ControlState`][flet.ControlState] of a button,
+    [`ControlState`][flet.] of a button,
     such as `HOVERED`, `FOCUSED`, `DISABLED` and others.
     """
 

sdk/python/packages/flet/src/flet/controls/context.py

@@ -10,13 +10,13 @@ class Context:
     Manages the context for Flet controls, including page reference
     and auto-update behavior.
 
-    Context instance is accessed via [`ft.context`][flet.context].
+    Context instance is accessed via [`flet.context`][flet.context].
     """
 
     @property
     def page(self) -> "Page":
         """
-        Returns the current [`Page`][flet.Page] associated with the context.
+        Returns the current [`Page`][flet.] associated with the context.
 
         For example:
 

sdk/python/packages/flet/src/flet/controls/control.py

@@ -19,39 +19,45 @@ class Control(BaseControl):
 
     expand: Optional[Union[bool, int]] = None
     """
-    Specifies whether/how this control should expand to fill available space in its parent layout.
+    Specifies whether/how this control should expand to fill available space in its
+    parent layout.
 
-    More information [here](https://docs.flet-docs.pages.dev/cookbook/expanding-controls/#expand).
+    More information
+    [here](https://docs.flet-docs.pages.dev/cookbook/expanding-controls/#expand).
 
     Note:
-        Has effect only if the direct parent of this control is one of the following controls, or their subclasses:
-        [`Column`][flet.Column], [`Row`][flet.Row], [`View`][flet.View], [`Page`][flet.Page].
+        Has effect only if the direct parent of this control is one of the following
+        controls, or their subclasses: [`Column`][flet.], [`Row`][flet.],
+        [`View`][flet.], [`Page`][flet.].
     """
 
     expand_loose: bool = False
     """
     Allows the control to expand along the main axis if space is available,
     but does not require it to fill all available space.
 
-    More information [here](https://docs.flet-docs.pages.dev/cookbook/expanding-controls/#expand_loose).
+    More information
+    [here](https://docs.flet-docs.pages.dev/cookbook/expanding-controls/#expand_loose).
 
     Note:
         If `expand_loose` is `True`, it will have effect only if:
 
         - `expand` is not `None` and
-        - the direct parent of this control is one of the following controls, or their subclasses:
-            [`Column`][flet.Column], [`Row`][flet.Row], [`View`][flet.View], [`Page`][flet.Page].
+        - the direct parent of this control is one of the following controls, or their
+            subclasses: [`Column`][flet.], [`Row`][flet.], [`View`][flet.],
+            [`Page`][flet.].
     """
 
-    col: ResponsiveNumber = 12  # todo: if dict, validate keys with those in parent (ResponsiveRow.breakpoints)
+    # todo: if dict, validate keys with those in parent (ResponsiveRow.breakpoints)
+    col: ResponsiveNumber = 12
     """
-    If a parent of this control is a [`ResponsiveRow`][flet.ResponsiveRow], 
+    If a parent of this control is a [`ResponsiveRow`][flet.],
     this property is used to determine
     how many virtual columns of a screen this control will span.
 
     Can be a number or a dictionary configured to have a different value for specific
     breakpoints, for example `col={"sm": 6}`.
-    
+
     This control spans the 12 virtual columns by default.
 
     /// details | Dimensions
@@ -99,7 +105,8 @@ class Control(BaseControl):
     its children are enabled.
 
     Note:
-        The value of this property will be propagated down to all children controls recursively.
+        The value of this property will be propagated down to all children controls
+        recursively.
 
     /// details | Example
         type: example