FastStream 文档贡献指南从本地构建到可测试代码示例的完整流程【免费下载链接】faststreamAsynchronous Python framework for event-driven services. A thin client for Kafka, RabbitMQ, NATS, Redis and MQTT with full access to native broker features, plus AsyncAPI docs, in-memory tests and observability out of the box.项目地址: https://gitcode.com/GitHub_Trending/fa/faststream本篇指南面向所有希望为 FastStream 项目贡献文档的开发者。你将学会如何在不安装完整 FastStream 项目的前提下搭建本地文档环境、使用just与uv启动实时预览服务器并掌握 FastStream 文档的链接规范、代码示例嵌入规则与配套测试要求最终提交一份可被项目组直接接受的文档 PR。你能以哪些方式帮助完善文档FastStream 官方文档仓库位于docs/目录官方欢迎所有形式的文档贡献主要包括三类指正不准确之处包括事实性错误、表述歧义与拼写错误typo提出编辑建议针对某个具体章节的措辞、结构与组织方式给出修改意见主动补充内容新增使用场景、配置说明、最佳实践或示例代码。上述任何反馈都可以通过 GitHub 上的 discussions 中配置的i18n多语言插件docs_structure: folder以docs/en/为默认英文文档目录可以印证翻译工作正是这套多语言体系运转的重要一环。快速开始搭建本地文档开发环境开发 FastStream 文档并不需要安装整个 FastStream 项目——文档的构建与预览只依赖just、uv和文档仓库本身这与直接为框架源码贡献是两条相互独立的路径。第一步安装 justfilejust 是 FastStream 项目统一使用的命令执行器。安装完成后在仓库根目录直接运行just即可查看项目定义的全部可用命令及其说明仓库根目录的 justfile 中为每条命令都标注了[doc(...)]描述。第二步安装 uvuv。第三步克隆仓库并启动本地文档服务器克隆仓库后在根目录执行just docs-serve即可启动本地文档服务器。just docs-serve在 justfile 中的真实定义是just _docs live 8000 {{params}}而_docs实际执行的是cd docs uv run --frozen python docs.py {{params}}也就是说它调用的是 docs/docs.py 中定义的 Typer 命令live默认端口8000。此后文档文件的一切改动都会通过 MkDocs 的实时重载hot-reload立即反映到本地站点上。若需要执行一次完整的构建包含全部依赖与扩展处理使用just docs-serve --full--full对应docs.py中live命令的full参数它会先执行完整构建生成 API 参考、更新 release notes再启动带实时重载的预览服务。深入文档构建流水线与其他常用命令理解just docs-serve背后的构建流水线有助于排查预览异常并选择正确的构建方式。从 docs/docs.py 的源码可以看出FastStream 的文档构建分两种模式快速构建_build_fast先调用create_api_docs中的remove_api_dir()删除 API 目录再调用render_navigation(, )生成不含 API 条目的导航docs/SUMMARY.md最后执行mkdocs build。由于跳过了耗时的 API 参考生成适合日常写作迭代。完整构建_build依次执行build_api_docs()生成 API 参考文档、update_release_notes()更新 docs/docs/en/release.md 发布说明再执行mkdocs build。对应just docs-build。常用命令速查表定义见 justfile命令作用底层实现just docs-serve启动带热重载的本地预览默认 8000 端口docs.py live 8000just docs-serve --full完整构建后再启动热重载预览docs.py live 8000 --fulljust docs-build仅执行一次完整构建不启动服务器docs.py buildjust docs-build-api只重新生成 API 参考文档docs.py build-api-docsjust docs-update-release-notes只更新发布说明docs.py update-release-notes其中 API 参考文档的生成逻辑位于 docs/create_api_docs.py它会通过importlib递归扫描faststream包及其全部公开子模块faststream/nats、faststream/kafka、faststream/rabbit、faststream/confluent、faststream/redis等为每个公开类与函数生成形如::: faststream.kafka.KafkaBroker的 mkdocstrings 标记文件再由 MkDocs 的mkdocstrings插件渲染为最终页面——这也是为什么在编辑涉及 API 签名的文档时建议使用--full或先跑一次just docs-build-api确保预览内容与源码同步。文档写作规范链接规范FastStream 文档对链接有严格的标记约定这直接关系到站点在版本前缀路径如/latest/下的正确渲染外部链接必须追加{.external-link target_blank}标记保证在新标签页打开并正确应用样式。例如[**Propan**](https://github.com/lancetnik/propan){.external-link target_blank}内部链接必须追加{.internal-link}标记且必须使用相对于目标.md文件的相对路径。禁止使用以/getting-started/...开头的根绝对路径——因为站点在版本化部署mike插件下总是挂在类似/latest/的前缀之下根绝对路径会直接 404。例如[contribution page](https://link.gitcode.com/i/3b6e1b25b0ec9ed62e0b00d6f2a92802){.internal-link}连续成串的链接不需要同时标记{.external-link}与{.internal-link}。当一段文字中出现大量外部链接时仅使用{target_blank}即可保持简洁例如[JSON](https://www.json.org/json-en.html){target_blank}、[MessagePack](https://msgpack.org/){target_blank}、[YAML](https://yaml.org/){target_blank}、[TOML](https://toml.io/en/){target_blank}这套属性标记之所以有效是因为 docs/mkdocs.yml 启用了attr_listMarkdown 扩展——它允许在链接后直接书写 HTML 属性。此外mkdocs.yml中还启用了content.code.copy代码复制按钮、content.code.annotate代码注解等特性都是写作时可以顺手利用的渲染能力。代码示例规范为了让文档中的代码示例可维护、可测试、可复用FastStream 制定了三条硬性规则1. Python 代码一律放在docs/docs_src/目录所有示例 Python 文件都存放在仓库的 docs/docs_src 目录下按主题与子主题组织目录结构。例如基础示例放在docs/docs_src/getting_started/basic.py风格的位置而发布publishing示例则按消息代理细分为docs/docs_src/getting_started/publishing/kafka/broker.py、docs/docs_src/getting_started/publishing/rabbit/broker.py、docs/docs_src/getting_started/publishing/redis/broker.py等。2. 用mdx_include将示例嵌入 Markdown 文档示例代码通过 MkDocs 的mdx_include扩展已在 docs/mkdocs.yml 中启用base_path: .直接嵌入到文档页面保证文档展示的代码与真实文件始终一致。标准写法如下python linenums1 hl_lines10 20 {! docs_src/getting_started/publishing/kafka/broker.py !} 规则说明当嵌入的文件超过 3 行时必须使用linenums关键字为代码块显示行号若需要高亮某些关键行用hl_lines配合以空格分隔的行号列表如上例中高亮第 10 行与第 20 行让读者一眼定位到核心代码。以实际文件为例docs/docs_src/getting_started/publishing/kafka/broker.py 展示了一个完整的发布-订阅链路handle订阅test-topic并向another-topic发布消息handle_next订阅another-topic并断言收到内容——这正是一个适合配合hl_lines讲解的典型示例。3. 在tests/docs/中为每个示例编写测试每个docs/docs_src/下的示例文件都必须在tests/docs/下建立对应的测试文件验证示例能够正确运行并符合预期行为。测试使用 pytest 编写必要时打上消息代理专属的 mark如require_aiokafka、require_nats、require_redis等定义于 tests/marks.py并在提交前确保全部通过。以 tests/docs/getting_started/publishing/test_broker.py 为例它同时覆盖了 kafka、confluent、rabbit、nats、redis、mqtt 六种消息代理的同构示例每个测试都从docs.docs_src.getting_started.publishing.broker.broker导入app、broker与订阅函数然后借助TestKafkaBroker(broker)、TestRabbitBroker(broker)等内存测试代理配合TestApp(app)运行并通过handle.mock.assert_called_once_with(...)断言订阅函数按预期被调用——这意味着文档中的示例不仅仅是能跑通的代码更是被 CI 持续验证过的活文档。这套源码文件 mdx_include 嵌入 配套测试的组合确保了文档示例具有三个关键特性版本可控示例与框架源码一同接受版本管理随版本演进同步更新可测试任何破坏示例的变更都会在测试中被拦截跨页面复用同一份示例文件可以在多个文档页面反复引用杜绝复制粘贴导致的漂移。提交你的贡献在本地完成全部修改示例代码、嵌入标记、配套测试并确认just docs-serve预览正常、相关测试通过后即可提交 Pull Request。项目组会对文档 PR 保持积极态度只需遵循上述链接规范与代码示例规范你的贡献就能被快速接纳。值得留意的是docs/mkdocs.yml 中配置的mike版本化插件canonical_version: latest与git-revision-date-localized插件显示页面最后编辑时间意味着每一篇被合并的文档都会成为 FastStream 版本化文档站点的一部分并记录你的贡献时间——这正是文档贡献者这一身份在项目中的真实痕迹。【免费下载链接】faststreamAsynchronous Python framework for event-driven services. A thin client for Kafka, RabbitMQ, NATS, Redis and MQTT with full access to native broker features, plus AsyncAPI docs, in-memory tests and observability out of the box.项目地址: https://gitcode.com/GitHub_Trending/fa/faststream创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考