--- name: docs-conventions description: Use when writing or reviewing Flet documentation, including Python docstrings (Google style, reST roles, admonitions), Markdown docs (cross-references, images, code examples), and sidebar navigation. --- # Documentation Conventions Docs live in `website/docs/`. Docusaurus renders them as the website. ## Python Docstrings Use **Google style** docstrings with sections: `Args:`, `Returns:`, `Raises:`, `Note:`, `Example:`, `Warning:`. ## Cross-references ### reST roles Prefer these in Python docstrings. CrocoDocs renders them as links in the API docs and they keep authoring terse when the auto-derived label is acceptable. **Supported roles:** `:class:`, `:attr:`, `:meth:`, `:func:`, `:data:`, `:mod:` ```python """ If a parent is a :class:`~flet.ResponsiveRow`, this property determines how many virtual columns the control spans. See :attr:`value` or :attr:`flet.Text.size` for the current selection. Calls :meth:`flet.Page.update` after modifying controls. """ ``` **Rules:** - **Qualified reference:** `:attr:`flet.Page.route`` — links to the member, displays inline code `Page.route` - **Extension reference:** `:attr:`flet_map.Map.animation_curve`` — links to the extension member, displays inline code `Map.animation_curve` - **Short display with `~`:** `:attr:`~flet.Page.route`` — links to the member, displays inline code `route` - **Local member (same class):** `:attr:`value`` — no qualifier needed - **Method with parens:** `:meth:`update`` — do NOT include `()` in the target For plain class references like `:class:`flet.Page`` and extension references like `:class:`flet_map.Map``, the website strips leading public package aliases automatically, so they display as inline code `Page` and `Map`. **Not supported:** - Custom labels like `:class:`my label `` — the label is always auto-derived from the target - Roles for symbols not in CrocoDocs API data degrade to inline code ### Xrefs Reference-style Markdown links of the form `[label][key]`, where `key` is the fully-qualified dotted symbol path (same form as reST role targets). Use as the default form for linking to API symbols from Markdown docs (`.md` / `.mdx`). Examples: ```markdown Class: [`Page`][flet.Page] Attribute: [`route`][flet.Page.route] Method: [`Page.update()`][flet.Page.update] Extension: [`Video.controls`][flet_video.Video.controls] Plain text: [the route attribute][flet.Page.route] ``` **When to prefer over the other forms:** - **Flexible labels** — the first `[ ]` accepts any text or inline code, unlike reST roles whose label is always auto-derived from the target - **Path-independent** — keys are dotted symbol paths, so links don't break when source files are moved, renamed, or restructured (unlike Markdown link paths with `../` and `#flet.X.y` anchors) - **Terser** than Markdown links to the same symbol — no relative path or anchor to maintain - **Greppable** — searching for the dotted key finds every reference to that symbol across all docs **Rules:** - The label (inside the first `[ ]`) is the rendered text — inline code or plain text - The key (inside the second `[ ]`) is the fully-qualified dotted path; do NOT include `()` for methods - Unresolved keys render as broken reference-style links (silent fallback) — verify with a build or `yarn crocodocs:generate` ### Markdown links Fallback for cases xrefs cannot cover: - docs-only Python strings — the `docs_reason` parameter of `@deprecated`, extracted validation messages, or short admonition text - links to non-API content (other doc pages, external URLs, anchors that aren't API symbols) - when the xref entry is missing and you need a working link before regenerating Use relative `.md` paths with dot-format anchors. Examples: ```markdown Control: [`Page`](../controls/page.md) Type: [`DragTargetEvent.global_position`](../types/dragtargetevent.md#flet.DragTargetEvent.global_position) Plain text: [route](../controls/page.md#flet.Page.route) Method: [`Page.update()`](../controls/page.md#flet.Page.update) ``` ## Admonitions in docstrings Google-style section headers render as Docusaurus admonitions: ```python """ Note: Has effect only if the direct parent is a :class:`~flet.Column`. Warning: This property is deprecated. Use :attr:`new_prop` instead. Example: Setting up a basic layout: ``ft.Column(controls=[ft.Text("Hello")])`` """ ``` Supported kinds: `Note`, `Warning`, `Danger`, `Tip`, `Info`. Unsupported kinds (e.g. `Limitation`, `Example`) are normalized to `note`. Empty admonitions are skipped. ## Admonitions ```markdown :::note Basic note without title. ::: :::warning[Important] Warning with a custom title. ::: ``` Supported types: `note`, `info`, `tip`, `warning`, `danger`. ## Front matter ```yaml --- class_name: "flet.Container" examples: "controls/container" example_images: "test-images/examples/material/golden/macos/container" example_media: "examples/controls/container/media" title: "Container" --- ``` - `examples` — root-relative path under `sdk/python/examples/` - `example_images` / `example_media` — root-relative under `website/static/docs/` ## Images Use the CrocoDocs `Image` component. Paths without `../` are resolved against `/docs/`: ```jsx import {Image} from '@site/src/components/crocodocs'; ``` For absolute paths (one-off assets in `static/`): ```jsx ``` ## Code examples ```jsx import {CodeExample} from '@site/src/components/crocodocs'; ``` Paths are relative to the configured `examples_root` (`sdk/python/examples/`). ## Inline HTML Use `...` in Python docstrings for keyboard keys, for example `Enter` or `Shift`. CrocoDocs preserves this tag in API docs. ## Sidebar Navigation Edit `website/sidebars.yml` to change navigation structure: ```yaml docs: Getting started: - getting-started/installation.md Controls: _generated_index: title: Controls slug: /controls description: Browse the complete catalog of controls. AlertDialog: controls/alertdialog.md ``` After editing, regenerate `sidebars.js`: ```bash cd website && yarn crocodocs:generate ```