mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
Merge branch 'doc/add_chinese_updates_in_contribute_folder' into 'master'
Doc/add chinese updates in contribute folder See merge request espressif/esp-idf!9455
This commit is contained in:
Krzysztof Budzynski
commit
8c01b60f8a
@ -3,11 +3,11 @@ Documentation Add-ons and Extensions Reference
|
||||
|
||||
This documentation is created using `Sphinx <http://www.sphinx-doc.org/>`_ application that renders text source files in `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_ (``.rst``) format located in :idf:`docs` directory. For some more details on that process, please refer to section :doc:`documenting-code`.
|
||||
|
||||
Besides Sphinx there are several other applications that help to provide nicely formatted and easy to navigate documentation. These applications are listed in section :ref:`setup-for-building-documentation` with the installed version numbers provided in file :idf_file:`docs/requirements.txt`.
|
||||
Besides Sphinx, there are several other applications that help to provide nicely formatted and easy to navigate documentation. These applications are listed in section :ref:`setup-for-building-documentation` with the installed version numbers provided in file :idf_file:`docs/requirements.txt`.
|
||||
|
||||
We build ESP-IDF documentation for two languages (English, Simplified Chinese) and for multiple chips. Therefore we don't run ``sphinx`` directly, there is a wrapper Python program ``build_docs.py`` that runs Sphinx.
|
||||
|
||||
On top of that we have created a couple of custom add-ons and extensions to help integrate documentation with underlining `ESP-IDF`_ repository and further improve navigation as well as maintenance of documentation.
|
||||
On top of that, we have created a couple of custom add-ons and extensions to help integrate documentation with underlining `ESP-IDF`_ repository and further improve navigation as well as maintenance of documentation.
|
||||
|
||||
The purpose of this section is to provide a quick reference to the add-ons and the extensions.
|
||||
|
||||
@ -17,9 +17,9 @@ Documentation Folder Structure
|
||||
|
||||
* The ESP-IDF repository contains a dedicated documentation folder :idf:`docs` in the root.
|
||||
* The ``docs`` folder contains localized documentation in :idf:`docs/en` (English) and :idf:`docs/zh_CN` (simplified Chinese) subfolders.
|
||||
* Graphics files and fonts common to localized documentation are contained in :idf:`docs/_static` subfolder
|
||||
* Graphics files and fonts common to localized documentation are contained in :idf:`docs/_static` subfolder.
|
||||
* Remaining files in the root of ``docs`` as well as ``docs/en`` and ``docs/zh_CN`` provide configuration and scripts used to automate documentation processing including the add-ons and extensions.
|
||||
* Sphinx extensions are provided in two directories, ``extensions`` and ``idf_extensions``
|
||||
* Sphinx extensions are provided in two directories, ``extensions`` and ``idf_extensions``.
|
||||
* A ``_build`` directory is created in the ``docs`` folder by ``build_docs.py``. This directory is not added to the `ESP-IDF`_ repository.
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ Config Files
|
||||
This file contains configuration common to each localized documentation (e.g. English, Chinese). The contents of this file is imported to standard Sphinx configuration file ``conf.py`` located in respective language folders (e.g. ``docs/en``, ``docs/zh_CN``) during build for each language.
|
||||
|
||||
:idf_file:`docs/sphinx-known-warnings.txt`
|
||||
There are couple of spurious Sphinx warnings that cannot be resolved without doing update to the Sphinx source code itself. For such specific cases respective warnings are documented in ``sphinx-known-warnings.txt`` file, that is checked during documentation build, to ignore the spurious warnings.
|
||||
There are couple of spurious Sphinx warnings that cannot be resolved without doing update to the Sphinx source code itself. For such specific cases, respective warnings are documented in ``sphinx-known-warnings.txt`` file, that is checked during documentation build, to ignore the spurious warnings.
|
||||
|
||||
|
||||
Scripts
|
||||
@ -75,14 +75,14 @@ These are Sphinx extensions developed for IDF that don't rely on any IDF-docs-sp
|
||||
Sphinx extensions that provides a ``.. list::`` directive that allows filtering of entries in lists based on whether a tag is set, as ``:tagname: - list content``. See the Python file for a more complete description.
|
||||
|
||||
:idf_file:`docs/extensions/html_redirects.py`
|
||||
During documentation lifetime some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt`
|
||||
During documentation lifetime, some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt`.
|
||||
|
||||
|
||||
Third Party Extensions
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- ``sphinxcontrib`` extensions for blockdiag, seqdiag, actdiag, nwdiag, rackdiag & packetdiag diagrams.
|
||||
- `Sphinx selective exclude`_ ``eager_only`` extension
|
||||
- `Sphinx selective exclude`_ ``eager_only`` extension.
|
||||
|
||||
.. _idf-specific extensions:
|
||||
|
||||
@ -94,9 +94,9 @@ Build System Integration
|
||||
|
||||
:idf:`docs/idf_extensions/build_system/`
|
||||
|
||||
Python package implementing a Sphinx extension to pull IDF build system information into the docs build
|
||||
Python package implementing a Sphinx extension to pull IDF build system information into the docs build.
|
||||
|
||||
* Creates a dummy CMake IDF project and runs CMake to generate metadata
|
||||
* Creates a dummy CMake IDF project and runs CMake to generate metadata.
|
||||
* Registers some new configuration variables and emits a new Sphinx event, both for use by other extensions.
|
||||
|
||||
Configuration Variables
|
||||
@ -112,7 +112,7 @@ New Event
|
||||
|
||||
``idf-info`` event is emitted early in the build, after the dummy project CMake run is complete.
|
||||
|
||||
Arguments are ``(app, project_description)`` where ``project_description`` is a dict containing the values parsed from ``project_description.json`` in the CMake build directory.
|
||||
Arguments are ``(app, project_description)``, where ``project_description`` is a dict containing the values parsed from ``project_description.json`` in the CMake build directory.
|
||||
|
||||
Other IDF-specific extensions subscribe to this event and use it to set up some docs parameters based on build system info.
|
||||
|
||||
@ -126,7 +126,7 @@ Other Extensions
|
||||
Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`.
|
||||
|
||||
:idf_file:`docs/idf_extensions/link_roles.py`
|
||||
This is an implementation of a custom `Sphinx Roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ to help linking from documentation to specific files and folders in `ESP-IDF`_. For description of implemented roles please see :ref:`link-custom-roles` and :ref:`link-language-versions`.
|
||||
This is an implementation of a custom `Sphinx Roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ to help linking from documentation to specific files and folders in `ESP-IDF`_. For description of implemented roles, please see :ref:`link-custom-roles` and :ref:`link-language-versions`.
|
||||
|
||||
:idf_file:`docs/idf_extensions/esp_err_definitions.py`
|
||||
Small wrapper extension that calls ``gen_esp_err_to_name.py`` and updates the included .rst file if it has changed.
|
||||
|
||||
@ -122,7 +122,7 @@ There is couple of tips, how you can make your documentation even better and mor
|
||||
|
||||
For practical example see :component_file:`nvs_flash/include/nvs.h`.
|
||||
|
||||
4. You may want to go even further and skip some code like e.g. repetitive defines or enumerations. In such case enclose the code within ``/** @cond */`` and ``/** @endcond */`` commands. Example of such implementation is provided in :component_file:`driver/include/driver/gpio.h`.
|
||||
4. You may want to go even further and skip some code like repetitive defines or enumerations. In such case, enclose the code within ``/** @cond */`` and ``/** @endcond */`` commands. Example of such implementation is provided in :component_file:`driver/include/driver/gpio.h`.
|
||||
|
||||
5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
|
||||
|
||||
@ -141,7 +141,7 @@ There is couple of tips, how you can make your documentation even better and mor
|
||||
Linking Examples
|
||||
----------------
|
||||
|
||||
When linking to examples on GitHub do not use absolute / hardcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted. The roles will transparently handle files that are located in submodules and will link to the submodule's repository with the correct commit ID.
|
||||
When linking to examples on GitHub, do not use absolute/hardcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted. The roles will transparently handle files that are located in submodules and will link to the submodule's repository with the correct commit ID.
|
||||
|
||||
The following roles are provided:
|
||||
|
||||
@ -199,9 +199,9 @@ The following types of diagrams are supported:
|
||||
* `Activity diagram <http://blockdiag.com/en/actdiag/index.html>`_
|
||||
* `Logical network diagram <http://blockdiag.com/en/nwdiag/index.html>`_
|
||||
|
||||
With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents.
|
||||
With this suite of tools, it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents.
|
||||
|
||||
For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image.
|
||||
For the diagram preparation, you can use an on-line `interactive shell`_ that instantly shows the rendered image.
|
||||
|
||||
Below are couple of diagram examples:
|
||||
|
||||
@ -327,7 +327,7 @@ When building the documents, Sphinx will use the above mentioned directive and r
|
||||
|
||||
The recommended way of doing it is adding the document to one of the list that gets included in ``conditional_include_dict`` in :idf_file:`docs/conf_common.py`, e.g. a document which should only be shown for BT capable targets should be added to ``BT_DOCS``. :idf_file:`docs/idf_extensions/exclude_docs.py` will then take care of adding it to ``exclude_patterns`` if the corresponding tag is not set.
|
||||
|
||||
If you need to exclude content inside a list or bullet points then this should be done by using the '':TAG:'' role inside the ''.. list:: '' directive.
|
||||
If you need to exclude content inside a list or bullet points, then this should be done by using the '':TAG:'' role inside the ''.. list:: '' directive.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -351,11 +351,11 @@ Would render in the documentation as:
|
||||
|
||||
This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
|
||||
|
||||
This extension also supports markup for defining local (within a single source file) substitutions. Place a definition like the following into a single line of the RST file::
|
||||
This extension also supports markup for defining local (within a single source file) substitutions. Place a definition like the following into a single line of the RST file:
|
||||
|
||||
{\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE", esp32="ESP32_VALUE", esp32s2="ESP32S2_VALUE"}
|
||||
|
||||
This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current RST file. For example::
|
||||
This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current RST file. For example:
|
||||
|
||||
{\IDF_TARGET_TX_PIN:default="IO3", esp32="IO4", esp32s2="IO5"}
|
||||
|
||||
|
||||
@ -1 +1,198 @@
|
||||
.. include:: ../../en/contribute/add-ons-reference.rst
|
||||
文档的附加工具和扩展功能指南
|
||||
=============================
|
||||
|
||||
: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 `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC`
|
||||
|
||||
删掉退格键后，将被渲染为
|
||||
|
||||
This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-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/Doxyfile`) 生成描述密钥头文件的 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
|
||||
|
||||
|
||||
@ -140,7 +140,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵
|
||||
链接到示例
|
||||
----------
|
||||
|
||||
链接到 GitHub 上的示例时，请不要使用绝对 URLs 或硬编码 URLs。请使用 Docutils 自定义角色生成链接。自动生成的链接指向项目库中 git commit 编号（或标记）的 tree 或 blob。这种做法可以确保 master 分支上的文件移动或删除时，链接不会失效。
|
||||
链接到 GitHub 上的示例时，请不要使用绝对 URLs 或硬编码 URLs。请使用 Docutils 自定义角色生成链接。自动生成的链接指向项目库中 git commit 编号（或标记）的 tree 或 blob。这种做法可以确保 master 分支上的文件移动或删除时，链接不会失效。Docutils 自定义角色将以透明的方式处理子模块中的文件，并使用正确的 commit ID 链接到子模块目录中。
|
||||
|
||||
有如下角色可以选择：
|
||||
|
||||
@ -189,7 +189,7 @@ CI build 脚本中添加了检查功能，查找 RST 文件中的硬编码链接
|
||||
|
||||
请考虑使用图表和图片解释表述的概念。
|
||||
|
||||
相比于长篇的表述，图例有时可以更好地描述复杂的理念、数据结构或算法。本项目库使用`blockdiag <http://blockdiag.com/en/index.html>`_ 工具包由简单的文本文件生成图表。
|
||||
相比于长篇的表述，图例有时可以更好地描述复杂的理念、数据结构或算法。本项目库使用 `blockdiag <http://blockdiag.com/en/index.html>`_ 工具包由简单的文本文件生成图表。
|
||||
|
||||
工具包支持下列图表类型：
|
||||
|
||||
@ -245,6 +245,132 @@ CI build 脚本中添加了检查功能，查找 RST 文件中的硬编码链接
|
||||
更多关于扩展的信息，请参阅 `sphinx.ext.todo <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todolist>`_ 的相关文档。
|
||||
|
||||
|
||||
为不同芯片书写通用文档
|
||||
----------------------
|
||||
|
||||
乐鑫各芯片的文档是基于现有文档完成的。为提高文档写作效率，使所写文档可重复用于其它芯片（以下称“目标”）文档中，我们为您提供以下功能：
|
||||
|
||||
|
||||
依据目标类型排除内容
|
||||
"""""""""""""""""""""
|
||||
|
||||
有时会出现某一内容只适用于一个目标的情况。这种情况下，你可以使用 ''.. only:: TAG'' 指令将这部分内容设为某个目标的专属内容，'TAG' 处替换为以下名称：
|
||||
|
||||
芯片名称：
|
||||
|
||||
* esp32
|
||||
* esp32s2
|
||||
|
||||
从 'sdkconfig.h' 中定义标识符，标识符由目标的默认 menuconfig 设置生成，例如：
|
||||
|
||||
* CONFIG_FREERTOS_UNICORE
|
||||
|
||||
从 soc '\*_caps' 头文件中定义标识符，例如：
|
||||
|
||||
* SOC_BT_SUPPORTED
|
||||
* SOC_CAN_SUPPORTED
|
||||
|
||||
示例：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
ESP32 specific content.
|
||||
|
||||
该指令也支持布尔逻辑操作符 'and'、'or' 和 'not'。
|
||||
|
||||
示例：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. only:: SOC_BT_SUPPORTED and CONFIG_FREERTOS_UNICORE
|
||||
|
||||
BT specific content only relevant for single-core targets.
|
||||
|
||||
该功能由 `Sphinx selective exclude <https://github.com/pfalcon/sphinx_selective_exclude>`_ 的扩展提供。
|
||||
|
||||
这个扩展有一个缺点，当你想要排除某个章节时，而这个章节后直接跟着一个加了标签的新章节，此时该功能无法成功操作。这种情况下，章节的标签将无法正确链接到下一节，但其它内容都可正确渲染。如遇这一情况，可暂时使用以下应急方法：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _section_1_label:
|
||||
|
||||
Section 1
|
||||
^^^^^^^^^
|
||||
|
||||
Section one content
|
||||
|
||||
.. _section_2_label:
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
_section_2_label:
|
||||
|
||||
Section 2
|
||||
^^^^^^^^^
|
||||
Section 2 content
|
||||
|
||||
':TAG:' 角色的作用为从树形目录中排除特定内容。例如：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
:esp32: configure-wrover
|
||||
configure-other-jtag
|
||||
|
||||
生成文档时，Sphinx 会使用上述提到的指令和角色，根据其被调用的目标标签来添加或排除某些内容。
|
||||
|
||||
.. note::
|
||||
|
||||
如希望根据目标的标签从 toctree 中排除一整个文档，则需同时更新 :idf_file:`docs/conf_common.py` 中的 ``exclude_patterns`` 列表，为其它目标排除该文档。否则，Sphinx 将发出一条错误警报：WARNING: document isn't included in any toctree。
|
||||
|
||||
对此推荐的解决方案是：将这个文档添加到 :idf_file:`docs/conf_common.py` ``conditional_include_dict`` 中的一个列表里，例如，一个仅供支持蓝牙的目标可见的文档应被添加至 ``BT_DOCS``。此后，如果该文档未设置对应的标签，则 :idf_file:`docs/idf_extensions/exclude_docs.py` 会将其添加至 ``exclude_patterns``。
|
||||
|
||||
|
||||
如果你需要从一个列表或项目符号条目中排除某一内容，应通过在 ''.. list:: '' 指令中使用 '':TAG:'' 角色来完成。
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. list::
|
||||
|
||||
:esp32: - ESP32 specific content
|
||||
:SOC_BT_SUPPORTED: - BT specific content
|
||||
- Common bullet point
|
||||
- Also common bullet point
|
||||
|
||||
|
||||
替代宏
|
||||
"""""""""""
|
||||
|
||||
如果你需要指向根据目标类型定义的芯片名称、工具链名称、路径名称或其它通用名称，可以选择使用 :idf_file:`docs/idf_extensions/format_idf_target.py` 提供的替代宏。
|
||||
|
||||
例如，以下 reStructuredText 内容：
|
||||
|
||||
This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC`
|
||||
|
||||
将在文档中渲染为：
|
||||
|
||||
This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
|
||||
|
||||
这一扩展也支持定义本地（在单个源文件中）替代名称的标记。请在 RST 文件的一行中插入下示定义语言：
|
||||
|
||||
{\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE", esp32="ESP32_VALUE", esp32s2="ESP32S2_VALUE"}
|
||||
|
||||
这样将在当前的 RST 文件中根据目标类型为 {\IDF_TARGET_SUFFIX} 标签定义一个替代名称。例如：
|
||||
|
||||
{\IDF_TARGET_TX_PIN:default="IO3", esp32="IO4", esp32s2="IO5"}
|
||||
|
||||
上例将为 {\IDF_TARGET_TX_PIN} 标签定义一个替代名称，当使用 esp32s2 标签调用 sphinx 时，{\IDF_TARGET_TX_PIN} 将被替代为 "IO5"。
|
||||
|
||||
.. note::
|
||||
|
||||
这样的单个文档定义指令可置于 .rst 文档中的任意位置（单独一行），指令名须以 ``IDF_TARGET_`` 为开头。
|
||||
|
||||
|
||||
汇总文档
|
||||
--------
|
||||
@ -261,7 +387,7 @@ Sphinx 新手怎么办
|
||||
|
||||
3. 想要查看在上传至 GitHub 前文档如何生成、呈现，有两种方式：
|
||||
|
||||
* 安装`Sphinx`_、 `Breathe`_、 `Blockdiag <http://blockdiag.com/en/index.html>`_ 和 `Doxygen <http://doxygen.nl/>`_ 本地生成文档，具体可查看下文。
|
||||
* 安装`Sphinx`_、`Breathe`_、`Blockdiag <http://blockdiag.com/en/index.html>`_ 和 `Doxygen <http://doxygen.nl/>`_ 本地生成文档，具体可查看下文。
|
||||
|
||||
* 在 `Read the Docs <https://readthedocs.org/>`_ 建立账号，在云端生成文档。 Read the Docs 免费提供文档生成和存储，且速度快、质量高。
|
||||
|
||||
@ -273,6 +399,9 @@ Sphinx 新手怎么办
|
||||
搭建环境本地生成文档
|
||||
--------------------
|
||||
|
||||
安装依赖项
|
||||
"""""""""""""
|
||||
|
||||
您可以安装下列包，通过搭建环境在电脑上本地生成文档：
|
||||
|
||||
1. Doxygen - http://doxygen.nl/
|
||||
@ -285,7 +414,12 @@ Sphinx 新手怎么办
|
||||
|
||||
添加 "sphinx_idf_theme" 包之后，文档将与 `ESP-IDF 编程指南 <https://docs.espressif.com/projects/esp-idf/en/latest/index.html>`_ 的风格保持一致。
|
||||
|
||||
不用担心需要安装太多包。除 Doxygen 和 sphinx_idf_theme 之外，其他包均使用纯 Python 语言，可一键安装。
|
||||
不用担心需要安装太多包。除 Doxygen 之外，其他包均使用纯 Python 语言，可一键安装。
|
||||
|
||||
.. important:: 目前仅支持 Python 3 版本生成文档，无法使用 Python 2。
|
||||
|
||||
Doxygen
|
||||
@@@@@@@
|
||||
|
||||
Doxygen 的安装取决于操作系统：
|
||||
|
||||
@ -309,7 +443,7 @@ Doxygen 的安装取决于操作系统：
|
||||
|
||||
.. note::
|
||||
|
||||
如果您是在 Windows 系统上安装（Linux 和 MacOS 用户可以跳过此说明），在安装 **之前**，请完成以下两步。这是安装 :ref:`add-illustrations` 提到的 "blockdiag" 依赖项的必须步骤。
|
||||
如果您是在 Windows MSYS2 系统上安装（Linux 和 MacOS 用户可以跳过此说明，不使用 MSYS2 的 Windows 用户需找到其它可替代系统），在安装 **之前**，请完成以下两步。这是安装 :ref:`add-illustrations` 提到的 "blockdiag" 依赖项的必须步骤。
|
||||
|
||||
1. 更新所有系统包：
|
||||
|
||||
@ -317,7 +451,7 @@ Doxygen 的安装取决于操作系统：
|
||||
|
||||
$ pacman -Syu
|
||||
|
||||
该过程可能需要重启 MSYS2 MINGW32 控制台重复上述命令，直至更新完成。
|
||||
该过程可能需要重启 MSYS2 MINGW32 控制台并重复上述命令，直至更新完成。
|
||||
|
||||
2. 安装 *blockdiag* 的依赖项之一 *pillow*：
|
||||
|
||||
@ -325,26 +459,14 @@ Doxygen 的安装取决于操作系统：
|
||||
|
||||
$ pacman -S mingw32/mingw-w64-i686-python-pillow
|
||||
|
||||
查看屏幕上的记录，确定 ``mingw-w64-i686-python-pillow-4.3.0-1`` 已安装。旧版本 *pillow* 无法运行。
|
||||
查看屏幕上的记录，确定 ``mingw-w64-i686-python-pillow-4.3.0-1`` 或更新的版本已安装。旧版本 *pillow* 无法运行。
|
||||
|
||||
Windows 安装 Doxygen 的缺点是 `blockdiag pictures <add-illustrations>`_ 字体不能正确加载，可能会存在乱码。在此问题解决之前，您可以使用 `interactive shell`_ 查看完整图片。
|
||||
|
||||
|
||||
sphinx_idf_theme
|
||||
@@@@@@@@@@@@@@@@
|
||||
其它应用
|
||||
@@@@@@@@@@@
|
||||
|
||||
编译 ``sphinx_idf_theme`` 需要同时使用 Python 和 JavaScript。因此，目前要进行本地编译还必须安装 `node.js <https://nodejs.org/en/download/>`_ ，命令如下：
|
||||
|
||||
::
|
||||
|
||||
cd ~/esp
|
||||
git clone https://github.com/espressif/sphinx_idf_theme.git
|
||||
cd sphinx_idf_theme
|
||||
npm install
|
||||
python setup.py build
|
||||
python setup.py install
|
||||
|
||||
我们计划在不久的将来支持安装预编译 ``sphinx_idf_theme``，给您带来的暂时不便，敬请谅解。
|
||||
|
||||
其他所有应用都是 `Python <https://www.python.org/>`_ 包，可以按照下列步骤一键安装：
|
||||
|
||||
@ -357,16 +479,73 @@ sphinx_idf_theme
|
||||
|
||||
安装步骤设定将 ESP-IDF 放在 ``~/esp/esp-idf`` 目录下，这是文档中使用的 ESP-IDF 默认地址。
|
||||
|
||||
更换到特定语言文件所在的目录::
|
||||
生成文档
|
||||
"""""""""
|
||||
|
||||
cd en
|
||||
::
|
||||
|
||||
cd ~/esp/esp-idf/docs
|
||||
|
||||
现在可以调用如下命令生成文档::
|
||||
|
||||
make html
|
||||
./build_docs.py build
|
||||
|
||||
这一步骤需要几分钟时间。完成后，文档会放置在 ``~/esp/esp-idf/docs/en/_build/html`` 文件夹下。您可以在网页浏览器中打开 ``index.html`` 查看。
|
||||
运行该命令后，系统将为 ESP-IDF 中所有可支持的语言和目标生成文档。这一过程将需要一些时间，但各文档会并行进行，速度取决于系统中 CPU 内核的个数（可通过 ``--sphinx-parallel-builds`` 选项修改该进程，详情可见 ``./build_docs.py --help``）。
|
||||
|
||||
如需生成某一语言的单个文档，运行::
|
||||
|
||||
./build_docs.py -l en -t esp32 build
|
||||
|
||||
其中，语言 (``-l``) 可选择 ``en`` 和 ``zh_CN``；目标 (``-t``) 可选择 ESP-IDF 中任意可支持的构建目标（如 ``esp32`` 和 ``esp32s2``）。
|
||||
|
||||
生成后的文档将位于 ``_build/<language>/<target>/html`` 文件夹中。如需查阅，请在网页浏览器中打开该目录里的 ``index.html``。
|
||||
|
||||
|
||||
生成文档子集
|
||||
""""""""""""""
|
||||
|
||||
生成整个文档可能速度较慢，因此，也可以选择只生成你所需的某个子集。
|
||||
|
||||
在指令中列出你需要生成的文档名称即可::
|
||||
|
||||
./build_docs.py -l en -t esp32 -i api-reference/peripherals/can.rst build
|
||||
|
||||
也可以同时生成多个文档::
|
||||
|
||||
./build_docs.py -l en -t esp32 -i api-reference/peripherals/can.rst api-reference/peripherals/adc.rst build
|
||||
|
||||
还可以生成通配文档::
|
||||
|
||||
./build_docs.py -l en -t esp32 -i api-reference/peripherals/* build
|
||||
|
||||
请注意，这一功能仅用于文档写作过程中的检查和测试。其生成的 HTML 页面并非渲染完成后的格式，比如，运行这一指令并不会生成一个列有所有文档的索引，而且如果其中涉及到任何还未生成的文档参考都将导致错误警报出现。
|
||||
|
||||
|
||||
生成 PDF
|
||||
""""""""""""
|
||||
|
||||
可以使用 ``build_docs.py`` 生成文档的 latex 和 PDF 格式，需安装以下 latex 工具包：
|
||||
|
||||
* latexmk
|
||||
* texlive-latex-recommended
|
||||
* texlive-fonts-recommended
|
||||
* texlive-xetex
|
||||
|
||||
同时，也需要安装以下字体：
|
||||
|
||||
* Freefont Serif、Sans 和 Mono OpenType fonts，类似于 Ubuntu 上的 ``fonts-freefont-otf`` 包
|
||||
* Lmodern，类似于 Ubuntu 上的 ``fonts-lmodern`` 包
|
||||
* Fandol，可从 `这里 <https://ctan.org/tex-archive/fonts/fandol>`_ 下载
|
||||
|
||||
现在，可通过以下指令生成文档的 PDF 格式::
|
||||
|
||||
./build_docs.py -bs latex -l en -t esp32 build
|
||||
|
||||
或者，也可以同时生成 html 和 PDF 格式::
|
||||
|
||||
./build_docs.py -bs html latex -l en -t esp32 build
|
||||
|
||||
Latex 和 PDF 文件将位于 ``_build/<language>/<target>/latex`` 文件夹中。
|
||||
|
||||
大功告成
|
||||
--------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user