前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载本文是 Flet 开源仓库内部文档工具链CrocoDocs位于 tools/crocodocs的深度技术指南。它讲解 CrocoDocs 如何把手工维护的 Markdown 文档、sidebars.yml导航配置、sdk/python/packages/*/src下的 Python 源码以及sdk/python/examples示例代码一站式转换为 Flet 官网Docusaurus可消费的sidebars.js、API 数据 JSON、MDX partials 与静态图片资源。读完本文你将掌握 CrocoDocs 的完整构建管线、pyproject.toml配置字段、sidebars.yml编写规则、API 交叉引用与告警块的渲染约定以及本地构建、watch 监听和产物验证的完整工作流。CrocoDocs 是什么CrocoDocs 是 Flet 项目内部自研的文档构建工具链用于为 Flet 的 Docusaurus 官网生成结构化的 API 制品structured API artifacts。它由两部分组成Python 命令行工具位于 tools/crocodocs通过uv --directory ./tools/crocodocs run crocodocs ...调用网站侧构建集成由 website/package.json 中的crocodocs:generate、start、build等脚本驱动并在 website/src/components/crocodocs/ 中配套 React 渲染组件。从工具定位看CrocoDocs 并不是文档编写工具而是一个**文档生成器**它消费源码与手工文档产出 Docusaurus 运行时所需的机器可读数据。其核心能力由crocodocs generate这一个命令完成见 cli.py。构建管线一次 generate 做什么crocodocs generate是 CrocoDocs 的主命令其内部编排逻辑实现在 generate.py 的run_generate()中共执行 8 个阶段生成侧边栏运行时配置把手工维护的website/sidebars.yml转换为website/sidebars.js扫描文档遍历website/docs下的.md/.mdx解析 front matter提取ClassAll symbol...等 API 组件标签块symbol blocks与 partial 引用写 manifest输出website/.crocodocs/docs-manifest.json记录每个路由页面对应的 symbol blocks生成 MDX partials产出 CLI 文档、跨平台权限、PyPI 包索引等.mdx片段生成代码示例数据扫描sdk/python/examples把示例源码文本写入website/.crocodocs/code-examples.json并基于各示例的pyproject.toml生成examples-metadata.json用 Griffe 提取 API 数据对文档引用的所有符号做类/函数/别名提取构建xref_map交叉引用表写 API 数据输出website/.crocodocs/api-data.json含 classes、functions、aliases、xref_map 与 canonical_map同步静态资产按asset_mappings配置把示例截图、golden 测试图片等批量复制进website/static/docs/。整个数据流可以用下图概括website/docs (hand-authored) website/static/docs/* (synced assets) website/sidebars.yml (hand-authored) ^ sdk/python/packages/*/src (Python source) | sdk/python/examples (code examples screenshots) - crocodocs generate - website/sidebars.js - website/.crocodocs/api-data.json - website/.crocodocs/code-examples.json - website/.crocodocs/*.mdx (partials) - website/static/docs/* (synced assets) Docusaurus - website/build从源码看run_generate()最后会通过Summary.print()输出一份统计见 generate.py包括扫描的文档数、加载的包数、序列化的符号数、生成的 partial 数、代码示例条目数、复制的资产数与 xref 条目数便于定位构建结果。值得注意的实现细节Griffe 提取通过子进程完成generate.py通过subprocess.run([sys.executable, griffe_extract_script.py])运行 griffe_extract_script.py以 JSON 作为 stdin/stdout 载荷并把所有包源码根加入PYTHONPATH见 generate.py。脚本内置SIGNATURE_LINE_LENGTH 60签名换行阈值并支持FLET_DOCS_FAST环境变量跳过耗时任务如 Ruff 签名格式化。公共别名解析generate.py会为flet_ads.BaseAd这类公开名 → 内部 qualname的别名生成带public_qualname字段的副本并在 xref_map 中为别名及其成员一并注册见 generate.py保证短名引用也能解析到正确的锚点。示例元数据_generate_examples_metadata()会读取每个示例目录pyproject.toml的[tool.flet]段判断webSupportedplatforms缺失、为空或包含web时视为支持 Web并提取metadata.title与metadata.docs_intro字段见 generate.py。本地构建与运行方式前置要求Node.js 20README 明确要求构建脚本通过nvm use 20切换uvPython 包管理器用于启动 CrocoDocs 与 flet-cli 相关子进程Yarnwebsite/package.json声明packageManager: yarn4.6.0。通过 yarn 构建整个站点nvm use 20 cd website yarn install yarn build # runs crocodocs generate docusaurus build yarn start # runs crocodocs watch docusaurus dev server其中yarn build实际执行的是 website/package.json 中定义的脚本链crocodocs:generate: cd .. uv --directory ./tools/crocodocs run crocodocs generate, build: yarn crocodocs:generate docusaurus build yarn docs:check, start: cd .. uv --directory ./tools/crocodocs run crocodocs watch --child-cwd ../../website -- yarn exec docusaurus start可以看到yarn build会在 Docusaurus 构建之前运行 CrocoDocs 生成构建完成后还会执行docs:check即bash .github/scripts/check_docs.sh website/build做产物校验。直接运行 CrocoDocs不经过 yarn直接执行生成命令uv --directory ./tools/crocodocs run crocodocs generateuv --directory ./tools/crocodocs会把进程工作目录切到工具目录这正是 CLI 解析所有相对路径的基准cli.py中crocodocs_root Path.cwd()pyproject.toml 里所有../../路径都相对于tools/crocodocs/解释见 cli.py。仅监听不启动站点uv --directory ./tools/crocodocs run crocodocs watch监听并同时启动子进程使用--分隔 CrocoDocs 参数与子进程命令uv --directory ./tools/crocodocs run crocodocs watch --child-cwd ../../website -- yarn exec docusaurus startwatch 模式增量再生成的监听循环yarn start通过crocodocs watch启动 Docusaurus 开发服务器。watch 模式的实现在 watch.py基于watchdog库见 pyproject.toml实现文件系统监听其行为要点如下启动时先执行一次完整generate随后监听输入变化在防抖窗口默认--debounce 0.5秒结束后自动重新生成 API 数据、侧边栏、partials、manifest 与同步资产监听的输入包括website/sidebars.yml单文件目标sdk/python/packages/*/src所有配置包源码仅.py后缀sdk/python/examples.py/.png/.gif/.svg配置的 CrocoDocs 资产源目录按各自include_exts匹配后缀。刻意排除website/docs/**/*.{md,mdx}Docusaurus 对这些文档本身有热重载能力每次改文案都触发全量再生成是冗余的。但如果新增了ClassAll symbol…这类结构性变更需要手动执行crocodocs generate或重启 watcher让 manifest 刷新见 watch.py 中build_watch_targets()的注释忽略目录白名单.git、.idea、.pytest_cache、.ruff_cache、.venv、__pycache__、build、dist、node_modules等目录内的变化不会触发再生成见 watch.py子进程联动watch 会以子进程方式拉起 dev server子进程退出时 watcher 也随之停止收到 SIGINT/SIGTERM 时优雅终止子进程超时 10 秒未退出则强制 kill见 watch.py单次生成失败不会中断监听异常会被捕获并打印等待下一次保存自动重试——这对文档贡献者边改边看、增量修复的工作流非常友好见 watch.py。此外CLI 还支持对generate/watch共用的命令行覆盖参数见 cli.py优先级高于 pyproject.toml参数说明--docs-path PATH覆盖docs_path--manifest-output PATH覆盖manifest_output--output PATH覆盖api_outputapi-data JSON 路径--sidebars-source PATH覆盖sidebars_source--sidebars-output PATH覆盖sidebars_output--base-url URL覆盖base_url如/docs--package NAME:PATH追加或覆盖 API 提取的包源码根可多次指定--extensions MODULE指定 Griffe 扩展模块可多次指定watch 专属参数--debounce SECS默认0.5与--child-cwd PATH子进程工作目录。CLI 退出码约定为 0 成功、2 错误见 cli.py。配置文件pyproject.toml 全面解读CrocoDocs 的全部配置集中在 tools/crocodocs/pyproject.toml由 config.py 的load_config()读取[tool.crocodocs]段并解析为CrocoDocsConfigdataclass。该文件还声明了 Python 依赖griffe2.0.0、PyYAML6.0、ruff0.13.1、watchdog4.0.0等与crocodocs crocodocs.cli:main的入口脚本。[tool.crocodocs]核心路径与全局设置仓库中的实际配置如下[tool.crocodocs] docs_path ../../website/docs manifest_output ../../website/.crocodocs/docs-manifest.json api_output ../../website/.crocodocs/api-data.json partials_output_dir ../../website/.crocodocs sidebars_source ../../website/sidebars.yml sidebars_output ../../website/sidebars.js base_url /docs extensions [flet.utils.griffe_deprecations] examples_root ../../sdk/python/examples各键含义键用途仓库实际值docs_pathwebsite/docs文档目录../../website/docsapi_outputapi-data.json输出位置../../website/.crocodocs/api-data.jsonmanifest_outputdocs-manifest.json输出位置../../website/.crocodocs/docs-manifest.jsonpartials_output_dir生成的.mdxpartial 目录../../website/.crocodocssidebars_sourcesidebars.yml源文件../../website/sidebars.ymlsidebars_output生成的sidebars.js../../website/sidebars.jsbase_url文档路由基础 URL/docsexamples_root代码示例根目录../../sdk/python/examplesextensions要加载的 Griffe 扩展[flet.utils.griffe_deprecations]注意extensions中配置的flet.utils.griffe_deprecations会被 griffe_extract_script.py 在包源码树中解析为绝对文件路径后加载用于处理 API 弃用标记。[tool.crocodocs.packages]API 提取的包清单该节把 Python import 名映射到源码根目录Griffe 提取时扫描这些目录。仓库当前配置覆盖了 22 个包从核心包到各扩展包[tool.crocodocs.packages] flet ../../sdk/python/packages/flet/src flet_ads ../../sdk/python/packages/flet-ads/src flet_audio ../../sdk/python/packages/flet-audio/src flet_audio_recorder ../../sdk/python/packages/flet-audio-recorder/src flet_camera ../../sdk/python/packages/flet-camera/src flet_charts ../../sdk/python/packages/flet-charts/src flet_cli ../../sdk/python/packages/flet-cli/src flet_code_editor ../../sdk/python/packages/flet-code-editor/src flet_color_pickers ../../sdk/python/packages/flet-color-pickers/src flet_datatable2 ../../sdk/python/packages/flet-datatable2/src flet_desktop ../../sdk/python/packages/flet-desktop/src flet_flashlight ../../sdk/python/packages/flet-flashlight/src flet_geolocator ../../sdk/python/packages/flet-geolocator/src flet_lottie ../../sdk/python/packages/flet-lottie/src flet_local_auth ../../sdk/python/packages/flet-local-auth/src flet_map ../../sdk/python/packages/flet-map/src flet_permission_handler ../../sdk/python/packages/flet-permission-handler/src flet_rive ../../sdk/python/packages/flet-rive/src flet_secure_storage ../../sdk/python/packages/flet-secure-storage/src flet_spinkit ../../sdk/python/packages/flet-spinkit/src flet_video ../../sdk/python/packages/flet-video/src flet_web ../../sdk/python/packages/flet-web/src flet_webview ../../sdk/python/packages/flet-webview/src从源码看generate 阶段会检查每个包根是否存在缺失的路径只产生 warning 而不会让构建失败见 generate.py。[tool.crocodocs.asset_mappings.*]静态资产批量同步该节定义要成批复制到website/static/docs/的目录。每个 mapping 含三个键键用途source_path要复制的源目录static_subpathwebsite/static/下的目标子路径config.py 会去掉首尾/include_exts要复制的文件扩展名列表仓库当前配置了三个 mapping[tool.crocodocs.asset_mappings.examples] source_path ../../sdk/python/examples static_subpath docs/examples include_exts [.png, .gif, .svg] [tool.crocodocs.asset_mappings.test-images] source_path ../../sdk/python/packages/flet/integration_tests static_subpath docs/test-images include_exts [.png, .gif, .svg] [tool.crocodocs.asset_mappings.test-images-charts] source_path ../../sdk/python/packages/flet-charts/integration_tests static_subpath docs/test-images-charts include_exts [.png, .gif, .svg]复制逻辑由 assets.py 的bulk_copy_assets()实现有两个值得注意的细节跳过SKIP_DIRS.dart_tool、.git、.venv、__pycache__、build、node_modules目录会被剪枝。注释里特别说明一次flet build ios会在build/下留下约 1.4 GB 的产物含 Swift Package Manager checkout其中大量图片会命中include_exts过滤器若不剪枝会被误拷进文档站点见 assets.py先 unlink 再 copy2目标文件先删除再写入因为copy2保留源文件权限位只读源SPM checkout 常为 0444会导致目标只读、下次运行无法重新打开写入见 assets.py。[tool.crocodocs.member_filters]成员可见性过滤控制哪些类成员从 API 输出中隐藏。仓库配置为[tool.crocodocs.member_filters] methods [init, before_update]即类的init与before_update方法不会出现在 API 文档中。过滤逻辑在 griffe_extract_script.py_is_filtered_member()同时检查all集合与该成员类型对应的集合。sidebars.yml 格式手写导航源website/sidebars.yml 是手写的侧边栏源文件仓库当前约 955 行CrocoDocs 在crocodocs generate期间把它转换为 website/sidebars.js。转换逻辑在 sidebars.py。语法规则顶层键成为侧边栏分类sidebar category嵌套映射键成为嵌套分类Label: path.md— 带标签的文档项- path.md— 文档项标签从页面标题推断生成时 label 为空串_doc_item()只在有标签时才写label字段见 sidebars.py_index: path.md— 分类链接指向该文档_meta— 分类选项如collapsed默认true通过_meta.collapsed覆盖见 sidebars.py_generated_index— Docusaurus 自动生成索引页支持title、slug、description输出为type: generated-index链接见 sidebars.py。其中_index、_generated_index、_meta是特殊键不会被当作普通子项输出见 sidebars.py。示例docs: Getting started: - index.md - getting-started/installation.md Tutorials: Calculator: tutorials/calculator.md ToDo: tutorials/todo.md Reference: Controls: _generated_index: title: Controls slug: /controls description: Browse the complete catalog of controls. AlertDialog: controls/alertdialog.md AppBar: controls/appbar.md Services: _index: services/index.md _meta: collapsed: false Audio: services/audio/index.md对应到仓库的真实sidebars.yml可以看到同样的模式被大规模使用例如Publishing Flet app分类使用_index: publish/index.mdWeb分类下再嵌套Dynamic Website、Hosting等多层结构见 website/sidebars.yml。生成的sidebars.js头部会写入 Generated by CrocoDocs from website/sidebars.yml. Do not edit by hand. 提示见 sidebars.py。文档页面格式约定Front matter 字段文档页通过 front matter 关联 API 符号、示例与图片--- class_name: flet.Container examples: controls/container # relative to examples_root example_images: test-images/examples/material/golden/macos/container # relative to /docs/ static root example_media: examples/controls/container/media # relative to /docs/ static root title: Container ---examples— 相对examples_root的路径供CodeExample组件使用example_images/example_media— 相对/docs/静态根的路径供Image组件使用无论文档文件嵌套多深都不需要../回溯见 README 说明这与 assets.py 同步资产的静态根路径设计一致。在 docstring 中使用 reST 交叉引用Python docstring 内使用 reST 风格交叉引用See :class:~flet.Page and :attr:flet.Control.visible.支持的 role:class:、:attr:、:meth:、:func:、:data:、:mod:、:obj:。渲染规则为网站自动剥离标签开头的flet.或ft.前缀例如:attr:flet.Control.visible显示为Control.visible~前缀继续缩短为末段例如:attr:~flet.Control.visible显示为visible。这些 reST 引用最终通过 xref_map 解析为具体路由与锚点——xref_map 由 generate.py 构建锚点格式为#flet.ClassName.member_name点分锚点字符串由_normalize_anchor()统一规范化去除引号、方括号、连续连字符等见 generate.py。在 Markdown 中使用交叉引用手写文档使用标准 Markdown 相对.md链接See [Page](https://link.gitcode.com/i/0d601ecea55c294ab60eb564c23395d7) and its [visible](https://link.gitcode.com/i/50500d556875c1d3d901651da8969331) property.锚点格式同样使用点分#flet.ClassName.member_name。这些引用由 website/plugins/remark-api-links.js 这个 Remark 插件在构建期解析。docstring 中的 Admonition提示块Google 风格的 docstring 段落会渲染为 Docusaurus admonition Note: This only works on mobile platforms. Warning: Deprecated since v0.80. 支持的 admonition 类型note、tip、info、warning、danger、caution。其他段落类型如Example:渲染为tipadmonition未识别的标题则按纯文本输出。ADmonition 的渲染支持位于 website/src/components/crocodocs/utils.js。文档中的 API 组件标签在 MDX 正文中文档通过ClassSummary、ClassMembers、ClassAll、IconGallery等组件标签声明需要渲染的符号。解析器 docs.py 用正则COMPONENT_TAG_RE匹配这些标签符号名可以写死nameFoo或从 front matter 解析name{frontMatter.key}并支持showRootHeading{true}选项。IconGallery虽在 website/src/components/IconGallery/crocodocs/目录之外但必须注册在COMPONENT_TAG_RE中——否则其符号会从 xref map 中消失导致 docstring 里的:class:~flet.Icons 无法解析、构建失败见 docs.py 的注释。渲染机制数据生成与页面渲染的分工CrocoDocs 负责生成数据Docusaurus 负责渲染数据。网站侧渲染组件位于 website/src/components/crocodocs/组件用途ClassAll.js完整类页面摘要 全部成员ClassSummary.js类头部签名、图片、继承关系ClassMembers.js属性、事件、方法列表ClassBlock.js单个成员渲染CodeExample.js内联代码示例 语法高亮Image.js文档图片自动加/docs/前缀实现根相对路径utils.jsMarkdown 渲染、xref 解析、admonition 支持此外图标类页面由 website/src/components/IconGallery/ 自行渲染成员用于Icons/CupertinoIcons的可搜索图标网格但同样注册在COMPONENT_TAG_RE中以保留 xref 映射。文档布局还涉及两个 swizzle 组件website/src/theme/DocItem/Layout/index.js 与 website/src/theme/DocCard/index.js以及 website/src/css/custom.css 中的自定义样式含 generated-index 网格。关键渲染特性README 归纳均有源码佐证基于 Griffe 的类/函数/别名渲染支持 Google 风格 docstring 分段限定锚点#flet.ClassName.member_namereST 交叉引用解析:class:、:attr:、:meth:等继承成员解析沿基类链回溯公共别名解析如flet_ads.BaseAd→flet_ads.base_ad.BaseAd为属性、事件、方法自动注入目录TOC。产物验证失效链接检查Docusaurus 在yarn build时会检查失效链接与锚点发现任何失效链接构建即失败。因此 CrocoDocs 文档中所有.md相对链接与#flet.ClassName.member_name锚点都必须在构建期可解析。失效图片与未解析 xref 检查构建完成后额外运行bash .github/scripts/check_docs.sh website/build该脚本扫描全部构建产物 HTML检查指向缺失文件的img标签以及输出中仍未解析的 reST xref:attr:、:class:等。CI 集成.github/workflows/ci.yml 中的docs_build任务在每次 push 时执行完整构建与验证并门禁发布任务——文档损坏时不允许发版Cloudflare Pages 通过pip install uv yarn build执行同一构建流程根目录设为website/。源码文件索引若想深入 CrocoDocs 内部核心源码分布如下。工具本体tools/crocodocs/src/crocodocs/cli.py — CLI 入口与参数解析config.py — 配置加载与 CLI 覆盖generate.py — 主生成命令的 8 阶段编排griffe_extract_script.py — Griffe API 提取子进程partials.py — MDX partial 生成CLI 文档、权限、PyPI 索引sidebars.py — sidebars YAML → JS 转换assets.py — 静态资产批量复制docs.py — Markdown/MDX 解析辅助frontmatter.py — front matter 解析pypi_index.py — PyPI 包索引渲染watch.py — 文件监听与自动再生成progress.py — 构建进度与统计输出scripts/ — CLI 与权限渲染脚本在sdk/pythonvenv 中通过子进程运行cli_to_md.py、cross_platform_permissions.py、linux_dependencies.py网站侧集成website/package.json — 构建脚本定义website/plugins/remark-api-links.js — Markdown xref 解析 Remark 插件website/src/components/crocodocs/ — React 渲染组件website/src/components/IconGallery/ — 图标搜索网格xref 注册website/src/theme/DocItem/Layout/index.js — swizzle 文档布局website/src/theme/DocCard/index.js — swizzle 卡片组件website/src/css/custom.css — 自定义样式总结CrocoDocs 把手写文档 Python 源码 示例代码三路输入统一收编为一次crocodocs generate调用输出侧边栏、API 数据、manifest、partials 与静态资产五类制品再交由 Docusaurus 渲染与校验并在 watch 模式下形成改源码即刷新文档的本地开发闭环。对 Flet 文档贡献者而言理解它的核心在于把握三层约定配置层[tool.crocodocs]及子节的路径与过滤设置、内容层front matter 字段、reST/Markdown 交叉引用与 admonition 语法、验证层构建期断链检查与check_docs.sh的图片/xref 扫描。这套数据生成与渲染分离的架构使得新增一个 Python 包、一批示例或一类控件文档都只需改配置与写文档而无需触碰站点渲染代码。赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐终极Mindustry攻略如何快速掌握自动化塔防RTS游戏终极Mindustry攻略如何快速掌握自动化塔防RTS游戏 Mindustry是一款将塔防策略与自动化生产完美融合的开源游戏让你在星际探索中体验基地建设与资游戏开发TripoSR从单图到3D网格的快速重建解决方案TripoSR从单图到3D网格的快速重建解决方案 面对传统3D建模流程的复杂性和耗时问题TripoSR提供了一种革命性的解决方案——基于Transforme数据目录数据治理数据血缘后端前端数据工程数据集成Composio 文档站 CI/CD 管线全解析从 GitHub Actions 工作流到自动化文档维护Composio 文档站 CI/CD 管线全解析从 GitHub Actions 工作流到自动化文档维护 本文以 Composio 仓库中 docs/agen人工智能AI Agent工具调用MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考