构建与维护中文文档

本页依据 文档基线与后续更新 中记录的 Zephyr main 快照更新。

本资料站使用 Sphinx 和 reStructuredText。构建只需要文档环境， 无需安装整个 Zephyr SDK。固件开发对 Python 的要求见 搭建开发环境并运行第一个应用。

安装依赖

在本 zephyr-cn 仓库根目录创建文档专用虚拟环境：

python3 -m venv .venv-doc
source .venv-doc/bin/activate
python -m pip install -r doc/requirements-doc.txt
make -C doc html

Windows 可用 py -m venv .venv-doc，然后在 cmd 激活 .venv-doc\Scripts\activate.bat。没有 make 时直接调用 Sphinx：

python -m sphinx -b html doc/source doc/_build/html

打开 doc/_build/html/index.html 浏览文档。当前依赖支持 Python 3.10 或更新版本的 文档构建环境；这与 Zephyr latest 固件开发所需的 Python 3.12 是两套要求。

严格构建

提交前检查解析警告、交叉引用与目录关系：

python -m sphinx -b html -n -W --keep-going doc/source doc/_build/html

必要时检查外部链接：

python -m sphinx -b linkcheck doc/source doc/_build/linkcheck

网络不可达、速率限制或外部网站策略也可能导致 linkcheck 失败， 应区分网络问题与实际失效链接。不要为消除错误随意删除有效来源。

内容与来源

页面使用 .rst；标题下划线应与显示宽度匹配，代码块显式指定语言。 用 :doc: 指向仓库页面，:ref: 指向显式标签，并把页面接入对应 toctree。 不需要逐一复制上游 API 源码；解释用途、调用约束、返回值与生命周期，并提供固定提交来源。

更新资料时，先检查 文档基线与后续更新 的基线，再对比对应上游文档、公共头文件和迁移指南。 官方说明与头文件出现差异时，记录所用提交并按该提交真实声明编写示例。 更新日期、来源和核对结果同步写入 doc/upstream-baseline.json。

更多语法见 Sphinx reStructuredText 文档。