FastStream 文档贡献指南：从本地构建到可测试代码示例的完整流程

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和文档仓库本身，这与直接为框架源码贡献是两条相互独立的路径。

第一步：安装 justfile

just 是 FastStream 项目统一使用的命令执行器。安装完成后，在仓库根目录直接运行：

just

即可查看项目定义的全部可用命令及其说明（仓库根目录的 justfile 中为每条命令都标注了[doc("...")]描述）。

第二步：安装 uv

uv。

第三步：克隆仓库并启动本地文档服务器

克隆仓库后，在根目录执行：

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）：

其中 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 linenums="1" hl_lines="10 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