esp-idf/docs/zh_CN/contribute/add-ons-reference.rst
Marius Vikhammer 548fd02d10 docs: initial update of programming guide for C3
Updates "front page" content, get-started, and api-guides with C3 content

Enable building and publishing of C3 docs in CI
2021-02-01 15:40:02 +08:00

199 lines
12 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

文档的附加工具和扩展功能指南
=============================
:link_to_translation:`en:[English]`
ESP-IDF 文档由 `Sphinx <http://www.sphinx-doc.org/>`_ 应用程序生成,使用 Sphinx 对 :idf:`docs` 目录中的 `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_ (``.rst``) 格式文档进行渲染。关于渲染过程的详细信息,请参阅 :doc:`documenting-code`
除 Sphinx 外,我们也使用了其它几种可为用户提供格式精美、便于查找的文档的应用程序。:ref:`setup-for-building-documentation` 中列出了这些应用程序,:idf_file:`docs/requirements.txt` 中列出了其相应的版本号。
ESP-IDF 中包含多种芯片的双语文档(英文,简体中文)。如运行 Sphinx不需直接使用 ``sphinx``,可运行 Python 程序包 ``build_docs.py``
在此基础上,我们也开发了一些自定义的附加工具和扩展功能,旨在帮助整合 `ESP-IDF`_ 目录下的各个文档以及更好地查找和维护文档内容。
本章节主要帮您快速了解这些附加工具和扩展功能。
文件夹结构
--------------
* ESP-IDF 根目录下包含一个专门放置文档的文件夹 :idf:`docs`
* ``docs`` 目录下的 :idf:`docs/en` (英文)和 :idf:`docs/zh_CN` (简体中文)子文件夹中包含本地化文档。
* 图像文件和本地化文档通用的字体包位于 :idf:`docs/_static` 子文件夹中。
* ``docs`` 根目录下以及 ``docs/en````docs/zh_CN`` 中的其它文件则提供了自动生成文档过程中所使用的配置和脚本,其中就包括本章节提到的附加工具和扩展功能。
* ``extensions````idf_extensions`` 两目录中提供了 Sphinx 的扩展功能。·
* 使用 ``build_docs.py````docs`` 文件夹中将自动创建一个 ``_build`` 目录。这个目录不会被添加到 `ESP-IDF`_ 项目库中。
附加工具和扩展功能指南
--------------------------------
配置文件
^^^^^^^^^^^^
:idf_file:`docs/conf_common.py`
该文件中包含每个本地化文档(包括英文文档、中文文档)所通用的配置信息。在文档每一次的构建过程中,该文件中的内容都将被导入至相应语言文件夹(包括,``docs/en````docs/zh_CN``)下的标准 Sphinx 配置文件 ``conf.py`` 中。
:idf_file:`docs/sphinx-known-warnings.txt`
Sphinx 中存在一些伪错误警报,这些警报只能通过更新 Sphinx 源代码本身来解决。针对这一情况,我们将这些伪错误警报列在了 ``sphinx-known-warnings.txt`` 文件中,每一次生成文档时系统都将检测该文件并忽略这些伪错误警报。
脚本
^^^^^^^
:idf_file:`docs/build_docs.py`
最高级可执行程序,负责运行 Sphinx 为单个或多个语言/目标生成文档。运行 ``build_docs.py --help`` 可查阅所有命令选项。
当使用 ``build_docs.py`` 运行 Sphinx 时,系统将为 ``idf_target`` 配置变量,并设置一个与该配置变量相同名称的 Sphinx 标签,然后使用一些环境变量将路径发送至 :ref:`IDF-Specific Extensions`
:idf_file:`docs/check_lang_folder_sync.sh`
同时更新双语文档时,语言文件夹 ``docs/en````docs/zh_CN`` 下的文档结构和文件名应保持一致,以减少两文档间的不一致。每一次生成文档时都将运行 ``check_lang_folder_sync.sh`` 脚本,检测是否出现上述不一致的情况。
.. note::
若一个新的章节为英语版本,且暂时还没有中文翻译,那么 ``zh_CN`` 文件夹中相应的中文文件内应写入 ``.. include::`` 指令,路径指向英文源文件。这样,中文读者将也可以看到英文版源文件。例如,如果 ``docs/zh_CN/contribute/documenting-code.rst`` 这一文件还没有中文翻译,则该文件中应写入 ``.. include:: ../../en/contribute/documenting-code.rst``
非文档脚本
^^^^^^^^^^^^^^^^
以下脚本除了生成文档之外,也可以用于其它用途:
:idf_file:`tools/gen_esp_err_to_name.py`
该脚本将检测整个 `ESP-IDF`_ 库,在源代码头文件中查找是否有错误代码和信息,然后在 :doc:`../api-reference/error-codes` 内生成一个 ``.inc`` 文件记录这些信息。
:idf_file:`tools/kconfig_new/confgen.py`
ESP-IDF :idf:`components` 的配置选项包含在每个部件目录下的 ``Kconfig`` 文件中,如 :idf_file:`components/bt/Kconfig`。该脚本将检测所有 ``component`` 目录并记录检测到的配置选项,然后在 :ref:`configuration-options-reference` 内生成一个 ``.inc`` 文件记录这些信息。
泛型扩展
^^^^^^^^^^^^^^^^^^
以下是专为 IDF 开发的 Sphinx 扩展,这些扩展不依赖于任何特定的 IDF 文档操作或配置:
:idf_file:`docs/extensions/toctree_filter.py`
Sphinx 扩展功能,优先于 ``:toctree:`` 指令,允许系统根据是否有标签(如 ``:tagname: toctree_entry``)来过滤条目。完整描述请参考 Python 文件。
:idf_file:`docs/extensions/list_filter.py`
Sphinx 扩展功能,提供一个 ``.. list::`` 指令,允许系统根据是否有标签(如 ``:tagname: - list content``)来过滤条目列表。完整描述请参考 Python 文件。
:idf_file:`docs/extensions/html_redirects.py`
在文档的维护过程中,一些源文件可能会转移位置或被重命名。这个 Sphinx 扩展功能便添加了一个重新导向机制,通过在 Sphinx 输出中生成静态 HTML 重新导向页面来为 URL 地址已改变的文档重新导向。该脚本与重新导向列表 ``html_redirect_pages`` 一起使用。``conf_common.py`` 将负责从 :idf_file:`docs/page_redirects.txt` 中生成这个重新导向列表。
第三方扩展
^^^^^^^^^^^^^^^^^^^^^^
- ``sphinxcontrib`` 为 blockdiag、seqdiag、actdiag、nwdiag、rackdiag & packetdiag 等图表的扩展
- `Sphinx selective exclude`_``eager_only`` 的扩展
.. _idf-specific extensions:
IDF 专属扩展
^^^^^^^^^^^^^^^^^^^^^^^
构建系统集成
###################
: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 专属的扩展功能均订阅该事件,并使用该事件根据系统构建信息来设置一些文档参数。
其它扩展
#############
:idf_file:`docs/idf_extensions/include_build_file.py`
``include-build-file`` 指令相当于是内置的 ``include-file`` 指令,只是文件路径是相对于 ``build_dir`` 来评估的。
:idf_file:`docs/idf_extensions/kconfig_reference.py`
订阅 ``idf-info`` 事件,并使用 confgen 从默认构建项目所使用的部件中生成 ``kconfig.inc`` 文件。之后,这个文件将被存储至 :doc:`/api-reference/kconfig` 中。
:idf_file:`docs/idf_extensions/link_roles.py`
一个自定义的 `Sphinx 角色 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ 的实现功能,帮助从文档链接到 `ESP-IDF`_ 项目中具体的文件和文件夹处。有关具体实现了哪些角色,请参阅 :ref:`link-custom-roles`:ref:`link-language-versions`
:idf_file:`docs/idf_extensions/esp_err_definitions.py`
小扩展包,调用 ``gen_esp_err_to_name.py`` 并更新修改后的 .rst 文件。
:idf_file:`docs/idf_extensions/gen_toolchain_links.py`
文档内许多地方提供了下载工具链的链接。为了整合这些链接,减少需要分别手动更新这些链接的时间,该脚本会根据 :idf_file:`tools/toolchain_versions.mk` 内的信息生成工具链下载链接和工具链解压代码片段。
:idf_file:`docs/idf_extensions/gen_version_specific_includes.py`
也是一个自动生成 reStructuredText 文本 ``.inc`` 的扩展功能,其中内容是基于当前 ESP-IDF 版本所写。
:idf_file:`docs/idf_extensions/util.py`
提供一系列实用功能,主要提高本地化生成文档(请参见 :ref:`setup-for-building-documentation`)的效率,节省后续再次生成文本所需时间。
:idf_file:`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 {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`.
同时,也支持使用以下语法标记本地(单个 rst 文件)替代文件的定义:
{\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}
这样将在当前的 rst 文件中定义标签 {\IDF_TARGET_TX_PIN} 的替换名称。
为了使用相同的格式规则规范文档内容,该扩展功能优先于默认的 ``.. include::`` 指令。
在依赖于字符排列方式的格式内无法使用这一替换方式,例如,表格内。
:idf_file:`docs/idf_extensions/latex_builder.py`
一个在 latex 生成器内添加 ESP-IDF 专属功能的扩展,优先于默认的 Sphinx latex 生成器。
在输出目录内创建并添加 espidf.sty latex 包,其中包含一些运行时所需变量的宏包,如 IDF-Target。
:idf_file:`docs/idf_extensions/gen_defines.py`
Sphinx 扩展,将 IDF 中的定义整合入 Sphinx 构建过程中,在 IDF 项目模型创建完成后开始运行。
解析这些定义值,并将其添加为 Sphinx 标签。
发出新的 'idf-defines-generated' 事件,其中有一个包含所有原始定义值的字典,其它扩展功能可以使用这些原始值生成相关数据。
:idf_file:`docs/idf_extensions/exclude_docs.py`
Sphinx 扩展,根据 conditional_include_dict {tag:documents} 标签更新已被排除的文档。如果文档设置有这个标签,则其将被添加至文档列表内。
同时也负责在使用 config 值 ``docs_to_build`` 生成文档时,排除不相关文档。此时,未在 ``docs_to_build`` 列表内的文档都将被排除。
订阅 ``idf-defines-generated`` 事件,因为该扩展功能需要根据 Sphinx 标签来决定需排除哪些文档。
:idf_file:`docs/idf_extensions/run_doxygen.py`
订阅 ``idf-defines-generated`` 事件,运行 Doxygen (:idf_file:`docs/doxygen/Doxyfile_common`) 生成描述密钥头文件的 XML 文件,然后运行 Breathe 将这些文件转换为可直接被添加至 API 参考页面的 ``.inc`` 文件。
将一些特定目标的自定义环境变量推入 Doxygen 中,包括项目的默认 ``sdkconfig.h`` 文件内定义的所有宏包以及 ``soc`` 部件 ``xxx_caps.h`` 的头文件中定义的所有宏包。这意味着,公共 API 头文件可以依赖于特定目标的配置选项或者 ``soc`` 功能头文件选项,如头文件中 ``#ifdef`` & ``#if`` 预处理器选项。
也就是说,我们可以根据生成文档的目标来生成不同的 Doxygen 文件。
有关这一流程的更多信息,请参考 :doc:`documenting-code`:doc:`../api-reference/template` 中的 **API 参考** 章节。
相关文档
-----------------
* :doc:`documenting-code`
.. _ESP-IDF: https://github.com/espressif/esp-idf/
.. _Sphinx selective exclude: https://github.com/pfalcon/sphinx_selective_exclude