Windmill Python Client 文档构建指南基于 pdoc 的 API 文档生成、发布与部署全解析【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill导读本文以 Windmill 仓库中 python-client/DOCS.md 为骨架完整解析wmillPython 客户端python-client/wmillAPI 文档的生成、版本发布与 Docker 部署全链路如何使用 pdoc 从 docstring 自动生成静态 HTML 文档、如何本地构建与提交、如何在发布流水线与 Docker 镜像中落地。读完本文你将掌握一套「docstring → pdoc → docs/ → 前端静态托管」的可复现文档工程实践并能结合仓库源码理解wmill客户端本身的 API 设计为自己的 Python 库建立同样的文档化体系。一、文档体系概览为何选择 pdocwmill是 Windmill 平台的 Python 官方客户端其 API 文档采用pdoc从源码 docstring 自动生成这与 TypeScript 客户端使用TypeDoc生成文档的思路完全一致——代码即文档文档随代码演进永不漂移。从仓库结构可以清晰看到这套体系的落点组成部分位置文档说明python-client/DOCS.md构建脚本python-client/build_pdoc.sh生成产物python-client/docs/提交进 git客户端源码python-client/wmill/wmill/__init__.py、client.py、s3_reader.py、s3_types.py构建/发布脚本python-client/publish.sh、python-client/install.shpdoc 生成的内容完全来自源码中的以下信息函数/类的 docstringGoogle 或 NumPy 风格均可类型注解type hints与返回值注解参数描述与默认值。这意味着想要文档质量高先要写好 docstring。pdoc 只是搬运工内容质量的决定权在代码注释里。二、文档构建原理从 docstring 到静态 HTML2.1 构建脚本逐行解析python-client/build_pdoc.sh 是整个构建链路的入口核心逻辑如下#!/bin/bash set -e # 1. 不存在 .venv 时创建虚拟环境并安装 pdoc 与 httpx if [ ! -d .venv ]; then python3 -m venv .venv .venv/bin/pip install -q pdoc httpx fi # 2. 以可编辑方式安装本地 wmill 包确保 pdoc 能 import 到最新源码 .venv/bin/pip install -q ./wmill # 3. 调用 pdoc 生成 HTML 到 docs/ 目录 .venv/bin/pdoc wmill -o docs三个步骤各司其职环境准备python3 -m venv .venv创建隔离虚拟环境.venv/已被 gitignore不会污染仓库set -e保证任何一步失败立即退出避免生成残缺文档包安装pip install ./wmill将 python-client/wmill/pyproject.toml 中声明的wmill包安装进虚拟环境pdoc 才能正确解析模块文档生成pdoc wmill -o docs以wmill为入口模块把整个包的模块文档输出到docs/。2.2 产物结构构建完成后docs/目录包含wmill.html主入口页展示wmill包概览与模块级函数如get_variable、run_script、get_resource、set_state、get_state等顶层便捷 APIwmill/client.htmlWindmill类的完整 API 参考覆盖全部方法与属性wmill/s3_types.htmlS3 集成类型与辅助类wmill/s3_reader.htmlS3 文件读取工具index.html、search.js文档首页与全文搜索支持。pdoc 自动为所有公开成员生成带类型签名、参数说明、返回值说明的参考页并内置搜索功能方便使用者快速检索。三、三种构建场景的完整流程3.1 本地构建开发期cd /path/to/windmill/python-client ./build_pdoc.sh脚本执行完成后打开file://$(pwd)/docs/wmill.html即可在浏览器中预览文档。本地构建的核心价值在于开发者在提交前就能看到自己 docstring 的最终渲染效果从而及时修正格式与描述。构建完成后应提交产物保证仓库中的docs/与源码同步git add docs/ git commit -m Update Python client documentation从仓库看docs/目录确实被提交进版本库python-client/docs/ 内含index.html、search.js、wmill.html等文件这正是「文档随代码入库」策略的直接体现。3.2 发布期构建CI/CD文档在发布流水线中自动重建。根据 python-client/publish.sh 的调用链publish.sh → build.sh → build_pdoc.sh即发布脚本先执行./build.sh完成客户端代码构建随后触发build_pdoc.sh重新生成文档再通过poetry publish将wmill发布到 PyPI。因此文档应当先于发布提交否则发布出去的包文档可能落后于实际代码。从 python-client/wmill/pyproject.toml 可以看到包发布元数据已就绪[tool.poetry] name wmill version 1.809.0 description A client library for accessing Windmill server wrapping the Windmill client API license Apache-2.0 [tool.poetry.dependencies] python ^3.7 httpx 0.24 include [wmill/py.typed] # 声明 PEP 561 类型信息注意wmill/py.typed的存在见 python-client/wmill/wmill/py.typed表明该包是 PEP 561 类型感知的这与「类型注解是文档的一部分」的理念一脉相承。3.3 Docker 镜像内联生产部署生产环境中的文档托管在 Windmill 前端应用内。仓库根目录 Dockerfile 第 80 行明确COPY /python-client/docs/ /frontend/static/pydocs/这条指令在构建镜像时把预先生成好的python-client/docs/整体复制到前端静态资源目录frontend/static/pydocs/因此在生产环境可通过https://app.windmill.dev/pydocs/wmill.html直接访问。注意这里是「复制预构建产物」而非「构建时重新生成」——所以要求docs/必须入库且保持最新Docker 构建环节不再依赖 Python 环境这也让镜像构建更快、更可复现。四、文档目录结构与模块映射生成文档与wmill包源码一一对应。入口模块 python-client/wmill/wmill/init.py 只有两行from .client import * from .s3_types import *这意味着顶层便捷 API 全部来自client.py的公开符号且S3Object等 S3 类型也被提升到包顶层。文档结构映射如下生成的 HTML 页面对应源码内容wmill.htmlwmill/init.py包概览、顶层便捷函数wmill/client.htmlwmill/client.pyWindmill类完整 API3729 行wmill/s3_types.htmlwmill/s3_types.pyS3 连接/对象类型wmill/s3_reader.htmlwmill/s3_reader.pyS3 读取工具从源码看wmill/s3_types.py 定义了S3Object、S3FsArgs、StorageOptions、PolarsConnectionSettings、Boto3ConnectionSettings、DuckDbConnectionSettings等 dict 子类型分别面向不同数据引擎Polars、boto3、DuckDB的 S3 连接配置——这些类型细节都能在s3_types.html中找到完整参考。五、写好 docstring 的规范文档质量的源头pdoc 的产出质量直接由 docstring 决定。仓库推荐 Google/NumPy 风格模板如下def my_function(param1: str, param2: int 0) - dict: Short description of function. Longer description with more details about what the function does and any important notes. Args: param1: Description of param1 param2: Description of param2 (default: 0) Returns: Description of return value Example: result my_function(test, 5) print(result) {status: ok} Windmill类源码本身就是这种规范的范例例如 wmill/client.py 中构造函数的 docstringdef __init__(self, base_urlNone, tokenNone, workspaceNone, verifyTrue): Initialize the Windmill client. Args: base_url: API base URL (defaults to BASE_INTERNAL_URL or WM_BASE_URL env) token: Authentication token (defaults to WM_TOKEN env) workspace: Workspace ID (defaults to WM_WORKSPACE env) verify: Whether to verify SSL certificates 同样get()/post()等方法的 docstring 也严格遵循Args/Returns结构。实践要点归纳必须写 docstring每个公开函数/类至少一行描述必须加类型注解def run_script(path: str) - dict比无注解版本在文档中多出完整签名信息示例放进 docstringExample:区块中的示例既能当 doctest 用也能渲染成可读示例描述简洁完整说清用途、参数含义、返回值、注意事项即可不做无关展开。六、与 TypeScript 客户端文档体系对照Windmill 的 Python 与 TypeScript 客户端采用完全同构的文档工程模式便于维护者横向理解与复用方面TypeScriptPython文档生成器TypeDocpdoc构建脚本build_typedoc.shbuild_pdoc.sh输出目录docs/docs/前端托管路径/tsdocs//pydocs/入口页面modules.htmlwmill.html两条链路共享相同的工程理念源码 docstring/注释驱动生成、产物提交进 git、构建期由脚本重建、部署期由 Dockerfile 复制进前端静态目录。理解其中一条即可快速迁移到另一条。七、源码佐证wmill客户端 API 与文档内容的对应为了让读者理解 pdoc 文档页背后到底「长什么样」这里从源码摘取几个与文档页直接对应的关键 API 实现均位于 wmill/client.py1. 顶层便捷函数与Windmill类。wmill/init.py 通过from .client import *导出全部公开 API文档wmill.html中列出的get_variable、run_script、get_resource、set_state、get_state等即来自Windmill类的实例方法封装使用示例见 python-client/wmill/README.md。2. 客户端初始化与环境变量约定。Windmill.__init__的取值优先级清晰base base_url or os.environ.get(BASE_INTERNAL_URL) or os.environ.get(WM_BASE_URL) self.token token or os.environ.get(WM_TOKEN) self.workspace workspace or os.environ.get(WM_WORKSPACE) self.path os.environ.get(WM_JOB_PATH)即显式参数 BASE_INTERNAL_URLWM_BASE_URLtoken 与 workspace 也遵循同样的「参数优先、环境变量兜底」模式workspace 缺失时直接断言报错这与文档页中每个方法的参数说明一一对应。3. 便捷 HTTP 封装。get()/post()是围绕httpx.Client的薄封装wmill/client.pyendpoint.lstrip(/)兼容带不带前导斜杠的写法失败时输出 URL、状态码与响应体后抛出异常。客户端底层使用httpx.Timeout(900.0)的超长超时适配长耗时任务。4. 作业运行 API。run_script_async已标记 deprecated建议改用run_script_by_path_async或run_script_by_hash_asyncpath 与 hash 互斥断言run_script则同步等待结果配套wait_job、get_job_status、get_result、cancel_job形成完整的作业生命周期管理——这些方法签名、参数、返回值都会被 pdoc 渲染进client.html。5. 本地 Mock 支持。通过WM_MOCKED_API_FILE环境变量指定 JSON 文件即可离线 mock variables/resourceswmill/client.py测试与文档示例都可脱离真实后端运行这也是 python-client/wmill/tests/ 中测试得以运行的基础。八、常见问题与最佳实践小结场景推荐做法新增/修改了公开 API同步更新 docstring 并本地运行./build_pdoc.sh预览文档落后于代码重建docs/并提交保持「docs 入库」策略发布新版本先提交最新docs/再执行 publish.sh 触发完整发布链路修改 S3 相关类型关注 s3_types.py 与s3_types.html的一致性类型提示丢失检查是否缺少注解、是否误用*导入导致符号未导出一句话总结这套文档工程把 API 文档的维护成本前移到写代码阶段docstring 类型注解用 pdoc 一键生成、入库、随镜像发布最终以/pydocs/静态页面服务所有使用者。这套模式在 Windmill 仓库中同时应用于 Python 与 TypeScript 两个客户端本身就是「低维护成本、高文档一致性」的工程化范例。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考