文档的附加工具和扩展功能指南¶
ESP-IDF 文档由 Sphinx 应用程序生成，使用 Sphinx 对 docs 目录中的 reStructuredText (.rst) 格式文档进行渲染。关于渲染过程的详细信息，请参阅 编写代码文档。
除 Sphinx 外，我们也使用了其它几种可为用户提供格式精美、便于查找的文档的应用程序。搭建环境本地生成文档 中列出了这些应用程序，docs/requirements.txt 中列出了其相应的版本号。
ESP-IDF 中包含多种芯片的双语文档（英文，简体中文）。如运行 Sphinx，不需直接使用 sphinx，可运行 Python 程序包 build_docs.py。
在此基础上，我们也开发了一些自定义的附加工具和扩展功能，旨在帮助整合 ESP-IDF 目录下的各个文档以及更好地查找和维护文档内容。
本章节主要帮您快速了解这些附加工具和扩展功能。
文件夹结构¶
ESP-IDF 根目录下包含一个专门放置文档的文件夹 docs。
docs目录下的 docs/en （英文）和 docs/zh_CN （简体中文）子文件夹中包含本地化文档。图像文件和本地化文档通用的字体包位于 docs/_static 子文件夹中。
docs根目录下以及docs/en和docs/zh_CN中的其它文件则提供了自动生成文档过程中所使用的配置和脚本，其中就包括本章节提到的附加工具和扩展功能。extensions和idf_extensions两目录中提供了 Sphinx 的扩展功能。·使用
build_docs.py，docs文件夹中将自动创建一个_build目录。这个目录不会被添加到 ESP-IDF 项目库中。
附加工具和扩展功能指南¶
配置文件¶
- docs/conf_common.py
该文件中包含每个本地化文档（包括英文文档、中文文档）所通用的配置信息。在文档每一次的构建过程中，该文件中的内容都将被导入至相应语言文件夹（包括，
docs/en、docs/zh_CN）下的标准 Sphinx 配置文件conf.py中。- docs/sphinx-known-warnings.txt
Sphinx 中存在一些伪错误警报，这些警报只能通过更新 Sphinx 源代码本身来解决。针对这一情况，我们将这些伪错误警报列在了
sphinx-known-warnings.txt文件中，每一次生成文档时系统都将检测该文件并忽略这些伪错误警报。
脚本¶
- docs/build_docs.py
最高级可执行程序，负责运行 Sphinx 为单个或多个语言/目标生成文档。运行
build_docs.py --help可查阅所有命令选项。当使用
build_docs.py运行 Sphinx 时，系统将为idf_target配置变量，并设置一个与该配置变量相同名称的 Sphinx 标签，然后使用一些环境变量将路径发送至 IDF 专属扩展。- docs/check_lang_folder_sync.sh
同时更新双语文档时，语言文件夹
docs/en和docs/zh_CN下的文档结构和文件名应保持一致，以减少两文档间的不一致。每一次生成文档时都将运行check_lang_folder_sync.sh脚本，检测是否出现上述不一致的情况。
注解
若一个新的章节为英语版本，且暂时还没有中文翻译，那么 zh_CN 文件夹中相应的中文文件内应写入 .. include:: 指令，路径指向英文源文件。这样，中文读者将也可以看到英文版源文件。例如，如果 docs/zh_CN/contribute/documenting-code.rst 这一文件还没有中文翻译，则该文件中应写入 .. include:: ../../en/contribute/documenting-code.rst。
非文档脚本¶
以下脚本除了生成文档之外，也可以用于其它用途：
- tools/gen_esp_err_to_name.py
该脚本将检测整个 ESP-IDF 库，在源代码头文件中查找是否有错误代码和信息，然后在 Error Codes Reference 内生成一个
.inc文件记录这些信息。- tools/kconfig_new/confgen.py
ESP-IDF components 的配置选项包含在每个部件目录下的
Kconfig文件中，如 components/bt/Kconfig。该脚本将检测所有component目录并记录检测到的配置选项，然后在 Configuration Options Reference 内生成一个.inc文件记录这些信息。
泛型扩展¶
以下是专为 IDF 开发的 Sphinx 扩展，这些扩展不依赖于任何特定的 IDF 文档操作或配置：
- docs/extensions/toctree_filter.py
Sphinx 扩展功能，优先于
:toctree:指令，允许系统根据是否有标签（如:tagname: toctree_entry）来过滤条目。完整描述请参考 Python 文件。- docs/extensions/list_filter.py
Sphinx 扩展功能，提供一个
.. list::指令，允许系统根据是否有标签（如:tagname: - list content）来过滤条目列表。完整描述请参考 Python 文件。- docs/extensions/html_redirects.py
在文档的维护过程中，一些源文件可能会转移位置或被重命名。这个 Sphinx 扩展功能便添加了一个重新导向机制，通过在 Sphinx 输出中生成静态 HTML 重新导向页面来为 URL 地址已改变的文档重新导向。该脚本与重新导向列表
html_redirect_pages一起使用。conf_common.py将负责从 docs/page_redirects.txt 中生成这个重新导向列表。
第三方扩展¶
sphinxcontrib为 blockdiag、seqdiag、actdiag、nwdiag、rackdiag & packetdiag 等图表的扩展Sphinx selective exclude 为
eager_only的扩展
IDF 专属扩展¶
构建系统集成¶
docs/idf_extensions/build_system/
Python 包实现了一个 Sphinx 扩展功能，即将 IDF 构建系统信息拉入文档构建中
创建一个 CMake IDF 项目模型，并运行 CMake 生成元数据。
注册一些新的配置变量并发出一个 Sphinx 新事件，这些信息都用于其它扩展功能中。
配置变量¶
docs_root- $IDF_PATH/docs 目录的绝对路径idf_path- IDF_PATH 变量的值，未设置环境时为 IDF_PATH 的绝对路径build_dir- 运行build_docs.py时自动创建的文档生成目录，默认为_build/<lang>/<target>idf_target- IDF_TARGET 的值。build_docs.py应负责在 Sphinx 命令行中设置该值。
新事件¶
CMake 项目模型运行完成后，系统将在构建初期发出 idf-info 事件。
参数为 (app, project_description)，其中 project_description 是一个字典，其中包含从 CMake 构建目录中的 project_description.json 内解析出的值。
其它 IDF 专属的扩展功能均订阅该事件，并使用该事件根据系统构建信息来设置一些文档参数。
其它扩展¶
- docs/idf_extensions/include_build_file.py
include-build-file指令相当于是内置的include-file指令，只是文件路径是相对于build_dir来评估的。- docs/idf_extensions/kconfig_reference.py
订阅
idf-info事件，并使用 confgen 从默认构建项目所使用的部件中生成kconfig.inc文件。之后，这个文件将被存储至 Project Configuration 中。- docs/idf_extensions/link_roles.py
一个自定义的 Sphinx 角色 的实现功能，帮助从文档链接到 ESP-IDF 项目中具体的文件和文件夹处。有关具体实现了哪些角色，请参阅 链接到示例 和 链接到其他语言文档。
- docs/idf_extensions/esp_err_definitions.py
小扩展包，调用
gen_esp_err_to_name.py并更新修改后的 .rst 文件。- docs/idf_extensions/gen_toolchain_links.py
文档内许多地方提供了下载工具链的链接。为了整合这些链接，减少需要分别手动更新这些链接的时间，该脚本会根据 tools/toolchain_versions.mk 内的信息生成工具链下载链接和工具链解压代码片段。
- docs/idf_extensions/gen_version_specific_includes.py
也是一个自动生成 reStructuredText 文本
.inc的扩展功能，其中内容是基于当前 ESP-IDF 版本所写。- docs/idf_extensions/util.py
提供一系列实用功能，主要提高本地化生成文档（请参见 搭建环境本地生成文档）的效率，节省后续再次生成文本所需时间。
- docs/idf_extensions/format_idf_target.py
通过将 idf_target 发送至 Sphinx 命令行替换 target 相关名称的扩展功能。例如：
This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with {IDF_TARGET_TOOLCHAIN_PREFIX}-gcc with CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC
删掉退格键后，将被渲染为
This is a ESP32, with /esp32/soc.c, compiled with xtensa-esp32-elf-gcc with CONFIG_ESP32_MULTI_DOC.
同时，也支持使用以下语法标记本地（单个 rst 文件）替代文件的定义： {IDF_TARGET_TX_PIN:default=”IO3”,esp32=”IO4”,esp32s2=”IO5”}
这样将在当前的 rst 文件中定义标签 {IDF_TARGET_TX_PIN} 的替换名称。
为了使用相同的格式规则规范文档内容，该扩展功能优先于默认的
.. include::指令。在依赖于字符排列方式的格式内无法使用这一替换方式，例如，表格内。
- docs/idf_extensions/latex_builder.py
一个在 latex 生成器内添加 ESP-IDF 专属功能的扩展，优先于默认的 Sphinx latex 生成器。
在输出目录内创建并添加 espidf.sty latex 包，其中包含一些运行时所需变量的宏包，如 IDF-Target。
- docs/idf_extensions/gen_defines.py
Sphinx 扩展，将 IDF 中的定义整合入 Sphinx 构建过程中，在 IDF 项目模型创建完成后开始运行。
解析这些定义值，并将其添加为 Sphinx 标签。
发出新的 ‘idf-defines-generated’ 事件，其中有一个包含所有原始定义值的字典，其它扩展功能可以使用这些原始值生成相关数据。
- docs/idf_extensions/exclude_docs.py
Sphinx 扩展，根据 conditional_include_dict {tag:documents} 标签更新已被排除的文档。如果文档设置有这个标签，则其将被添加至文档列表内。
同时也负责在使用 config 值
docs_to_build生成文档时，排除不相关文档。此时，未在docs_to_build列表内的文档都将被排除。订阅
idf-defines-generated事件，因为该扩展功能需要根据 Sphinx 标签来决定需排除哪些文档。- docs/idf_extensions/run_doxygen.py
订阅
idf-defines-generated事件，运行 Doxygen (docs/doxygen/Doxyfile_common) 生成描述密钥头文件的 XML 文件，然后运行 Breathe 将这些文件转换为可直接被添加至 API 参考页面的.inc文件。将一些特定目标的自定义环境变量推入 Doxygen 中，包括项目的默认
sdkconfig.h文件内定义的所有宏包以及soc部件xxx_caps.h的头文件中定义的所有宏包。这意味着，公共 API 头文件可以依赖于特定目标的配置选项或者soc功能头文件选项，如头文件中#ifdef&#if预处理器选项。也就是说，我们可以根据生成文档的目标来生成不同的 Doxygen 文件。
有关这一流程的更多信息，请参考 编写代码文档 和 API Documentation Template 中的 API 参考 章节。