A2A 文档站点构建实战：MkDocs + Sphinx 双引擎下的本地开发与自动发布

A2A 文档站点构建实战MkDocs Sphinx 双引擎下的本地开发与自动发布【免费下载链接】A2AAgent2Agent (A2A) is an open protocol enabling communication and interoperability between opaque agentic applications.项目地址: https://gitcode.com/gh_mirrors/a2a/A2A本文围绕 Agent2AgentA2A协议仓库中的文档维护入口docs/README.md系统讲解 A2A 官方文档站的完整技术栈与构建链路如何在本地用 MkDocs 预览文档、如何用 Sphinx 生成 Python SDK 的 API 参考、以及 GitHub Actions 如何自动构建并发布多版本文档。读完本文你将掌握这套文档体系的目录组织、配置要点、命令行操作与 CI/CD 发布机制能够独立为 A2A 协议文档提交高质量贡献。一、文档仓库的整体布局A2A 仓库把文档源码与项目代码放在同一仓库内所有 Markdown 源文件集中在docs/目录站点级配置放在仓库根目录的mkdocs.yml中。从当前仓库结构可以确认以下关键目录docs/index.md站点首页docs/topics/核心技术主题包括协议概述、核心概念、任务生命周期、Agent 发现、企业级特性、流式与异步、多租户、A2A 与 MCP 的关系等docs/extensions.md与docs/topics/extensions.md扩展机制与自定义协议绑定docs/specification.md、docs/whats-new-v1.md、docs/definitions.md协议规范相关内容docs/sdk/SDK 概览与 Python API 参考由 Sphinx 生成详见下文docs/tutorials/python/面向 Python 的 8 篇系列教程docs/blog/官方博客文章specification/a2a.proto协议的 protobuf 定义是协议规范与 JSON Schema 的源头。一个值得注意的细节是mkdocs.yml通过exclude_docs: README.md把docs/README.md排除在最终构建产物之外——它专门面向仓库贡献者充当“文档的文档”而不是站点页面的一部分。二、本地开发快速上手docs/README.md给出的本地开发流程只有四步下面逐一展开并补充命令细节。1. 克隆仓库并进入目录git clone https://gitcode.com/gh_mirrors/a2a/A2A.git cd A2A2. 安装文档依赖pip install -r requirements-docs.txtrequirements-docs.txt位于仓库根目录它声明的依赖直接决定了文档站的能力边界各组件作用如下依赖包作用mkdocs-material文档站主题提供 Material Design 风格的界面与大量开箱即用特性mkdocs-redirects旧路径 301 重定向插件配合mkdocs.yml中的redirect_maps使用a2a-sdk[all]安装 Python SDK 及其全部可选依赖供 Sphinx 生成 API 文档时导入包mikeMkDocs 多版本发布插件负责把不同版本部署到独立目录并管理latest别名mkdocs-macros-plugin在 Markdown 中启用宏模板站点配置中通过.mkdocs/macros模块加载自定义宏sphinxPython 文档生成器用于构建 SDK API 参考furoSphinx 的 HTML 主题见docs/sdk/python/conf.pymyst-parserSphinx 的 Markdown 解析器使 Sphinx 可以消费.md源文件proto-schema-parser解析 protobuf Schema配合规格文档生成使用tabulate表格渲染辅助工具注意requirements-docs.txt是a2a-sdk[all]的直接依赖方因此安装时会一并拉取 SDK 及其运行时依赖CI 中还会使用uv pip install --system --upgrade -r requirements-docs.txt进行安装本地若已安装uv也可采用同样方式加速。3. 启动本地预览mkdocs serve该命令会在本地启动一个开发服务器默认监听http://127.0.0.1:8000并实时监听docs/下 Markdown 文件的改动保存即热重载。配合mkdocs.yml中开启的content.code.copy、content.code.select、navigation.instant等特性可以直接在浏览器中验证代码块复制按钮、即时导航等最终用户交互效果。4. 提交文档变更文档修改遵循仓库常规的贡献流程提交 PR、由维护者评审合并合并到main分支后会自动触发文档站重建与发布无需手动部署。三、文档站工作原理MkDocs Material 主题docs/README.md明确指出文档站基于 MkDocs 与 mkdocs-material 主题构建下面结合仓库根目录的mkdocs.yml展开说明这套机制的运转细节。站点元信息site_name: A2A Protocol site_url: https://a2a-protocol.org/ site_description: - The official documentation for the Agent2Agent (A2A) protocol. ... site_author: The Linux Foundation site_dir: site edit_uri: edit/main/docs/edit_uri为页面头部“编辑此页”入口提供基础路径exclude_docs: README.md将贡献者文档排除在站点外extra.a2a_version通过!ENV [MIKE_VERSION, dev]读取环境变量缺省为dev用于在页面上显示当前版本标识。导航nav组织nav是站点信息架构的单一事实来源当前结构分为五大区块Documentation协议入门、A2A 与 MCP、核心概念、任务生命周期、Agent 发现、企业级特性、流式与异步、多租户Extensions扩展总览、自定义协议绑定、扩展与绑定治理Specification规范总览、v1.0 新特性、协议定义ResourcesSDK 概览、Python API 参考、Python 快速入门教程8 篇Community / Blog社区、路线图、合作伙伴与博客。这种“先主题、后规范、再资源”的层级设计让新手可以从docs/topics/what-is-a2a.md开始了解协议进阶用户可以直接跳到docs/specification.md查阅协议数据对象而开发者则在docs/tutorials/python/中按 1-8 编号循序渐进。主题与扩展theme块启用了 Material 主题的大量特性navigation.tabs顶部标签页、navigation.sections、navigation.indexes、navigation.footer、navigation.top、navigation.tracking以及toc.follow等并开启versioning.provider: mike支持多版本切换。markdown_extensions则显著增强了写作能力admonition提示框、pymdownx.tabbed标签页、pymdownx.superfences代码块增强并支持 Mermaid 图、pymdownx.snippets代码片段引用、pymdownx.highlight带行号的高亮、pymdownx.details可折叠内容与toc锚点等。这意味着贡献者写文档时可以放心使用这些语法最终站点会呈现与官方 A2A 文档一致的渲染效果。插件体系plugins: - blog: post_url_format: {date}/{slug} pagination_per_page: 1 - search - macros: module_name: .mkdocs/macros - redirects: redirect_maps: specification/agent-card.md: specification.md#5-agent-discovery-the-agent-card topics/push-notifications.md: topics/streaming-and-async.md ... - mike: canonical_version: latestredirects插件的redirect_maps维护了一批历史路径到新路径的映射例如旧版documentation.md重定向到topics/key-concepts.md保证外部书签和搜索引擎收录的旧链接不失效mike插件配合版本化部署使站点可以同时存在dev、latest及具体版本号等多个版本。四、CI/CD 自动构建与发布docs/README.md提到仓库中存在一个 GitHub Action 负责构建并发布文档到gh-pages分支该工作流位于.github/workflows/docs.yml其完整机制如下。触发条件on: push: branches: [main] paths: [.github/workflows/docs.yml, scripts/*.sh, requirements-docs.txt, mkdocs.yml, docs/**, .mkdocs/**, specification/a2a.proto] pull_request: branches: [main] paths: [...同上...] release: types: [published] workflow_dispatch: inputs: version: description: Version to deploy to (e.g., v1.0.0) required: true default: dev即合并到main、提交 PR、发布 Release、手动触发四种场景都会进入构建。注意paths过滤意味着只有文档相关文件含specification/a2a.proto变更时才值得重建文档站。构建流水线流水线在ubuntu-latest上依次执行检出代码fetch-depth: 0mike 需要完整 Git 历史来计算版本配置 Git 凭据由github-actions[bot]提交部署产物安装 Python 3.13 与uv并用uv pip install --system --upgrade -r requirements-docs.txt安装依赖安装 Bufprotobuf 工具链、Go 与protoc编译安装protoc-gen-jsonschema插件并克隆googleapis到third_party/运行./scripts/build_docs.sh生成协议规范文件与 SDK 文档运行bash scripts/build_llms_full.sh生成合并版llms-full.txt供 LLM 检索的聚合文档分场景部署PR 仅执行mkdocs build做校验push 到 main 执行mike deploy --push --update-aliases dev latest并mike set-default --push latestRelease 发布时以 tag 名如v1.0.0作为版本号部署手动触发则使用输入的 version 参数。- name: Deploy development version from main branch if: github.event_name push github.ref refs/heads/main run: | mike deploy --push --update-aliases dev latest mike set-default --push latest bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}deploy_root_files.sh用于把 404 页面等根文件部署到gh-pages分支而--update-aliases与set-default组合确保了“最新版”指向当前默认版本。整个流程把文档发布做成了零人工干预的自动化管道。五、统一构建脚本 build_docs.shCI 中调用的scripts/build_docs.sh是文档构建的统一入口它在调用 MkDocs 之前完成三件关键工作Schema 新鲜度检查比较specification/a2a.proto与specification/json/a2a.json的修改时间若 proto 更新则调用scripts/proto_to_json_schema.sh重新生成 JSON Schema规范文件发布把specification/json/a2a.json与specification/a2a.proto复制到docs/spec/使 MkDocs 可以把协议原始定义作为站点资产发布SDK 文档构建调用scripts/build_sdk_docs.sh生成 Python API 参考。脚本支持两种调用模式./scripts/build_docs.sh # 仅执行 mkdocs build本地构建 ./scripts/build_docs.sh deploy # 执行 mike deploy版本化发布构建完成后脚本还会把adrs/下的架构决策记录ADR复制到site/adrs/——例如 adr-001-protojson-serialization.md 记录了 protojson 序列化方案的技术决策它们虽不在docs/内但会作为规范页面的一部分发布。从脚本逻辑可以推断所有先校验、再生成、后构建的顺序都被集中在了这一个脚本里本地与 CI 因而能共享完全一致的构建行为。六、构建 Python SDK 文档Sphinxdocs/README.md专门用一节说明 Python SDK 文档的 Sphinx 构建方式这是贡献者最常执行的手动操作。1. 前置依赖pip install -r requirements-docs.txt该命令与文档站依赖完全相同在仓库根目录执行requirements-docs.txt位于根目录其中sphinx、furo、myst-parser三项是 SDK 文档构建的直接支撑。2. 构建 HTML 文档sphinx-build -b html docs/sdk/python docs/sdk/python/api该命令以docs/sdk/python含index.rst与conf.py为 Sphinx 源目录把生成的 HTML 输出到docs/sdk/python/api/。生成完成后直接在浏览器打开docs/sdk/python/api/index.html即可查看 Python SDK 的完整 API 参考。从mkdocs.yml的 nav 可以看出docs/sdk/python/api/index.html正是被 MkDocs 作为“Python API Reference”页面嵌入站点导航的。3. Sphinx 配置要点docs/sdk/python/conf.py揭示了 SDK 文档的构建细节extensions [ sphinx.ext.autodoc, # 从 docstring 自动生成 API 文档 sphinx.ext.autosummary, # 自动生成摘要与存根 sphinx.ext.napoleon, # 支持 Google 风格 docstring myst_parser, # 支持 Markdown 源文件 ] autosummary_generate True html_theme furo autodoc_member_order alphabetical也就是说SDK 的 API 参考并非手写而是由autodoc直接从a2a包的 docstring 抽取而成——这解释了为什么构建前必须先安装a2a-sdk[all]。4. 完整自动化构建流程scripts/build_sdk_docs.sh给出了与手写命令等价的完整流程uv venv .doc-venv source .doc-venv/bin/activate uv pip install -r requirements-docs.txt uv pip install a2a-sdk # PyPI 包名为 a2a-sdk导入名为 a2a sphinx-apidoc -f -e -o docs/sdk/python a2a-package-path sphinx-build -b html docs/sdk/python docs/sdk/python/_build/html sphinx-build -b text docs/sdk/python docs/sdk/python/_build/text cp -r docs/sdk/python/_build/html docs/sdk/python/api脚本先创建隔离的虚拟环境.doc-venv用sphinx-apidoc -f -e为a2a包的每个模块生成独立.rst页面-f强制覆盖、-e每模块独立页再分别构建 HTML 与纯文本两种格式最后把 HTML 复制到docs/sdk/python/api/供 MkDocs 集成。需要注意的是脚本会删除并重建.doc-venv因此本地反复运行不会残留脏环境。七、贡献文档的实用建议综合以上机制为 A2A 文档做贡献时可以遵循以下工作流先阅读 docs/README.md 与仓库根目录的 mkdocs.yml确认改动是否涉及nav、插件或重定向映射克隆仓库后在根目录执行pip install -r requirements-docs.txt然后mkdocs serve实时预览若修改的是docs/topics/、docs/tutorials/等站点页面直接编辑 Markdown 即可若修改 Python SDK 相关页面需按第六节流程重新生成docs/sdk/python/api/若改动涉及协议本身specification/a2a.proto本地可先运行./scripts/build_docs.sh触发 Schema 重新生成确认specification/json/a2a.json同步更新后再提交提交 PR 后CI 会自动执行mkdocs build校验构建是否通过合并到main后文档会自动发布为dev/latest版本无需人工干预。这套“MkDocs 管站点、Sphinx 管 API、GitHub Actions 管发布、mike 管版本”的四层架构使 A2A 协议文档既保持了 Markdown 写作的低门槛又保证了 API 参考与协议 Schema 的单源自动生成是开源项目文档工程化的一个完整范本。【免费下载链接】A2AAgent2Agent (A2A) is an open protocol enabling communication and interoperability between opaque agentic applications.项目地址: https://gitcode.com/gh_mirrors/a2a/A2A创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考