文档的附加工具和扩展功能指南

[English]

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/endocs/zh_CN 中的其它文件则提供了自动生成文档过程中所使用的配置和脚本,其中就包括本章节提到的附加工具和扩展功能。

  • extensionsidf_extensions 两目录中提供了 Sphinx 的扩展功能。·

  • 使用 build_docs.pydocs 文件夹中将自动创建一个 _build 目录。这个目录不会被添加到 ESP-IDF 项目库中。

附加工具和扩展功能指南

配置文件

docs/conf_common.py

该文件中包含每个本地化文档(包括英文文档、中文文档)所通用的配置信息。在文档每一次的构建过程中,该文件中的内容都将被导入至相应语言文件夹(包括,docs/endocs/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/endocs/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 excludeeager_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 参考 章节。

相关文档