v1: Use macros across the docs, move "raises" to properties, restructure navigation (#5681)

* Refactor docs to use templated metadata and helpers

Updated documentation files for Flet controls to use frontmatter metadata (class_name, examples, example_images) and templated helper functions (class_summary, class_members, class_all_options). Example paths and image references now use template variables for consistency. Removed browsercontextmenu.md. This improves maintainability and enables more dynamic documentation generation.

* Refactor and clarify docstring Raises sections in controls

Moved and consolidated 'Raises' documentation for validation errors into relevant property docstrings across multiple control classes. This improves clarity and consistency in error documentation for Flet controls, making it easier for developers to understand validation requirements for each property.

* Refactor image embedding in docs to use macro

Replaced Markdown image syntax and caption comments with the `{{ image(...) }}` template across multiple documentation files for consistency and improved maintainability.

* Restructure and update Flet documentation

Deleted outdated contributing and tutorials docs, moved extension and reference docs to new locations, updated links and section headers for clarity, and improved organization of documentation files. This refactor streamlines navigation and prepares for future documentation improvements.

* cleanup CI workflow

---------

Co-authored-by: ndonkoHenri <[email protected]>

Author: FeodorFitsner

.github/workflows/ci.yml

@@ -351,7 +351,6 @@ jobs:
             local PACKAGE_NAME="$1"
             local SUFFIX=""
             local FLAVOR="full"
-
             if [[ "$PACKAGE_NAME" == "flet-desktop-light" ]]; then
               SUFFIX="-light"
               FLAVOR="light"
@@ -534,11 +533,10 @@ jobs:
           source "$SCRIPTS/common.sh"
           patch_python_package_versions
           uv build --package flet-web --wheel
+
           rm -rf "packages/flet-web/src/flet_web/web"
           uv build --package flet-web --sdist
 
-          ls -laR dist
-
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -591,7 +589,7 @@ jobs:
   py_publish:
     name: Publish Python packages to PyPI
     runs-on: ubuntu-latest
-    # if: startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main'
+    if: startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main'
     needs:
       - python_tests
       - build_flet_package
@@ -615,10 +613,8 @@ jobs:
           # remove client to avoid glob conflicts with its contents
           rm -rf dist/client
 
-          ls -laR
-
           for pkg in flet flet_cli flet_desktop flet_desktop_light flet_web; do
-            uv publish --dry-run dist/**/${pkg}-*
+            uv publish dist/**/${pkg}-*
           done
 
   # ==============

sdk/python/packages/flet/docs/ads/bannerad.md

@@ -14,8 +14,7 @@ example_images: ../examples/controls/ads/media
 --8<-- "{{ examples }}/example_1.py"
 ```
 
-![example_1]({{ example_images }}/example_1.gif){width="80%"}
-/// caption
-///
+{{ image(example_images + "/example_1.gif", alt="example_1", width="80%") }}
+
 
 {{ class_members(class_name) }}

sdk/python/packages/flet/docs/ads/index.md

@@ -39,9 +39,8 @@ pip install flet-ads  # (1)!
 --8<-- "{{ examples }}/example_1.py"
 ```
 
-![example_1]({{ example_images }}/example_1.gif){width="80%"}
-/// caption
-///
+{{ image(example_images + "/example_1.gif", alt="example_1", width="80%") }}
+
 
 ## Packaging
 

sdk/python/packages/flet/docs/ads/interstitialad.md

@@ -14,8 +14,7 @@ example_images: ../examples/controls/ads/media
 --8<-- "{{ examples }}/example_1.py"
 ```
 
-![example_1]({{ example_images }}/example_1.gif){width="80%"}
-/// caption
-///
+{{ image(example_images + "/example_1.gif", alt="example_1", width="80%") }}
+
 
 {{ class_members(class_name) }}

sdk/python/packages/flet/docs/cli/index.md

@@ -1,6 +1,4 @@
----
-title: Flet CLI
----
+# Flet CLI
 
 Flet command-line interface (CLI) provides an easy way to create, run, test and package Flet apps.
 

sdk/python/packages/flet/docs/contributing/extensions/index.md

@@ -1 +1,5 @@
-::: flet.AdaptiveControl
+---
+class_name: flet.AdaptiveControl
+---
+
+{{ class_all_options(class_name) }}

sdk/python/packages/flet/docs/contributing/index.md

@@ -1,15 +1,22 @@
+---
+class_name: flet.AlertDialog
+examples: ../../examples/controls/alert_dialog
+example_images: ../examples/controls/alert_dialog/media
+---
+
+{{ class_summary(class_name) }}
+
 ## Examples
 
 [Live example](https://flet-controls-gallery.fly.dev/dialogs/alertdialog)
 
 ### Modal and non-modal dialogs
 
 ```python
---8<-- "../../examples/controls/alert_dialog/modal_and_non_modal.py"
+--8<-- "{{ examples }}/modal_and_non_modal.py"
 ```
 
-![modal-and-non-modal](../examples/controls/alert_dialog/media/modal_and_non_modal.gif){width="80%"}
-/// caption
-///
+{{ image(example_images + "/modal_and_non_modal.gif", alt="modal-and-non-modal", width="80%") }}
+
 
-::: flet.AlertDialog
+{{ class_members(class_name) }}