mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: Provide Chinese translation for template.rst and platformio.rst
This commit is contained in:
renpeiying
parent
db86b59330
commit
e99b500b9d
@ -1,12 +1,14 @@
|
||||
API Documentation Template
|
||||
==========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
|
||||
*INSTRUCTIONS*
|
||||
|
||||
1. Use this file (:idf_file:`docs/en/api-reference/template.rst`) as a template to document API.
|
||||
2. Change the file name to the name of the header file that represents documented API.
|
||||
2. Change the file name to the name of the header file that represents the documented API.
|
||||
3. Include respective files with descriptions from the API folder using ``..include::``
|
||||
|
||||
* README.rst
|
||||
@ -24,15 +26,15 @@ Overview
|
||||
*INSTRUCTIONS*
|
||||
|
||||
1. Provide overview where and how this API may be used.
|
||||
2. Where applicable include code snippets to illustrate functionality of particular functions.
|
||||
2. Include code snippets to illustrate functionality of particular functions when applicable.
|
||||
3. To distinguish between sections, use the following `heading levels <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_:
|
||||
|
||||
* ``#`` with overline, for parts
|
||||
* ``*`` with overline, for chapters
|
||||
* ``=``, for sections
|
||||
* ``-``, for subsections
|
||||
* ``^``, for subsubsections
|
||||
* ``"``, for paragraphs
|
||||
* ``=`` for sections
|
||||
* ``-`` for subsections
|
||||
* ``^`` for subsubsections
|
||||
* ``"`` for paragraphs
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
@ -43,9 +45,9 @@ Application Example
|
||||
|
||||
1. Prepare one or more practical examples to demonstrate functionality of this API.
|
||||
2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
|
||||
3. Place example in this folder complete with ``README.md`` file.
|
||||
3. Place example in this folder, and add ``README.md`` file.
|
||||
4. Provide overview of demonstrated functionality in ``README.md``.
|
||||
5. With good overview reader should be able to understand what example does without opening the source code.
|
||||
5. With good overview readers should be able to understand what example does without opening the source code.
|
||||
6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
|
||||
7. Include flow diagram and screenshots of application output if applicable.
|
||||
8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
|
||||
@ -59,9 +61,9 @@ API Reference
|
||||
|
||||
*INSTRUCTIONS*
|
||||
|
||||
1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
|
||||
1. ESP-IDF repository provides automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
|
||||
|
||||
2. Update is done on each documentation build by invoking Sphinx extension :`esp_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile`.
|
||||
2. Update is done on each documentation build by invoking Sphinx extension ``esp_extensions/run_doxygen.py`` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile`.
|
||||
|
||||
3. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that is used to generate corresponding ``*.inc`` files::
|
||||
|
||||
@ -71,9 +73,9 @@ API Reference
|
||||
../components/esp32/include/esp_wifi.h \
|
||||
../components/esp32/include/esp_smartconfig.h \
|
||||
|
||||
4. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include/exclude material based on the ``IDF_TARGET`` value.
|
||||
4. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include or exclude material based on the ``IDF_TARGET`` value.
|
||||
|
||||
5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g., ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
|
||||
5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated, e.g., ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
|
||||
|
||||
6. To show contents of ``*.inc`` file in documentation, include it as follows::
|
||||
|
||||
@ -100,4 +102,4 @@ API Reference
|
||||
|
||||
8. In any case, to generate API reference, the file :idf_file:`docs/doxygen/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented.
|
||||
|
||||
9. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
|
||||
9. When changes are committed and documentation is built, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
|
||||
@ -3,6 +3,8 @@
|
||||
PlatformIO
|
||||
##########
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. image:: ../../_static/platformio-logo.png
|
||||
:target: https://platformio.org/?utm_source=docs.espressif.com
|
||||
|
||||
@ -16,23 +18,15 @@ What is PlatformIO?
|
||||
is a cross-platform embedded development environment with out-of-the-box support
|
||||
for ESP-IDF.
|
||||
|
||||
Since ESP-IDF support within PlatformIO is not maintained by the Espressif team,
|
||||
please report any issues with PlatformIO directly to its developers in
|
||||
`the official PlatformIO repositories <https://github.com/platformio>`_.
|
||||
Since ESP-IDF support within PlatformIO is not maintained by the Espressif team, please report any issues with PlatformIO directly to its developers in `the official PlatformIO repositories <https://github.com/platformio>`_.
|
||||
|
||||
A detailed overview of the PlatformIO ecosystem and its philosophy can be
|
||||
found in `the official PlatformIO documentation <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_.
|
||||
A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official PlatformIO documentation <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_.
|
||||
|
||||
Installation
|
||||
~~~~~~~~~~~~
|
||||
|
||||
* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_
|
||||
is a toolset for embedded C/C++ development available on Windows, macOS and Linux
|
||||
platforms
|
||||
* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_
|
||||
is a command-line tool that consists of multi-platform build system, platform and
|
||||
library managers and other integration components. It can be used with a variety of
|
||||
code development environments and allows integration with cloud platforms and web
|
||||
* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_ is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms.
|
||||
* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_ is a command-line tool that consists of multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web
|
||||
services
|
||||
|
||||
Configuration
|
||||
@ -43,8 +37,7 @@ Please go through `the official PlatformIO configuration guide for ESP-IDF <http
|
||||
Tutorials
|
||||
~~~~~~~~~
|
||||
|
||||
- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis
|
||||
<https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
|
||||
- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis <https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
|
||||
|
||||
Project Examples
|
||||
~~~~~~~~~~~~~~~~
|
||||
@ -56,5 +49,5 @@ Next Steps
|
||||
|
||||
Here are some useful links for exploring the PlatformIO ecosystem:
|
||||
|
||||
- Learn more about `integrations with other IDEs/Text Editors <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_
|
||||
- Get help from `PlatformIO community <https://community.platformio.org/?utm_source=docs.espressif.com>`_
|
||||
- Learn more about `integrations with other IDEs or Text Editors <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_
|
||||
- Get help from `PlatformIO community <https://community.platformio.org/?utm_source=docs.espressif.com>`_
|
||||
@ -1 +1,105 @@
|
||||
.. include:: ../../en/api-reference/template.rst
|
||||
API 文档模板
|
||||
==========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. note::
|
||||
|
||||
*说明*
|
||||
|
||||
1. 使用此文件 (:idf_file:`docs/zh_CN/api-reference/template.rst`) 作为 API 参考文档模板。
|
||||
2. API 参考文档需和 API 的头文件名称保持一致。
|
||||
3. 使用 ``..include::`` 从 API 文件夹中添加相应的说明文件。
|
||||
|
||||
* README.rst
|
||||
* example.rst
|
||||
* ...
|
||||
|
||||
4. 可选择在此文件中直接提供描述。
|
||||
5. 完成后，删除所有的说明信息（类似本说明）和多余的头部信息。
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
.. note::
|
||||
|
||||
*撰写说明*
|
||||
|
||||
1. 提供概述，简要说明 API 的用途和使用方法。
|
||||
2. 必要时提供代码片段，以说明特定函数的功能。
|
||||
3. 用此 `文档 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ 中介绍的方式区分不同的章节标题：
|
||||
|
||||
* ``#`` 用于设置各部分，标题上下同时标记
|
||||
* ``*`` 用于设置章标题，标题上下同时标记
|
||||
* ``=`` 用于设置节标题
|
||||
* ``-`` 用于设置小节标题
|
||||
* ``^`` 用于设置小小节标题
|
||||
* ``"`` 用于设置段落标题
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
.. note::
|
||||
|
||||
*撰写说明*
|
||||
|
||||
1. 准备一个或多个实际示例，展示此 API 的功能。
|
||||
2. 每个示例应遵循 ``esp-idf/examples/`` 文件夹中项目的模式。
|
||||
3. 将示例放在此文件夹中，添加 ``README.md`` 文件。
|
||||
4. 在 ``README.md`` 中对展示的功能进行概述。
|
||||
5. 良好的概述让读者能够充分理解示例，而无需参考源代码。
|
||||
6. 按照示例的复杂程度，将代码描述分解成几个部分，并对每部分的功能进行概述。
|
||||
7. 必要时，添加流程图和应用程序的输出截图。
|
||||
8. 最后为本章节的每个示例添加对应链接，示例文件夹应位于 ``esp-idf/examples/`` 中。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
.. note::
|
||||
|
||||
*撰写说明*
|
||||
|
||||
1. ESP-IDF 仓库通过 :doc:`用 Doxygen 从头文件中检索代码标记 <../contribute/documenting-code>` 的方式自动更新 API 参考文档。
|
||||
|
||||
2. 通过调用 Sphinx 扩展工具 ``esp_extensions/run_doxygen.py``，对 :idf_file:`docs/doxygen/Doxyfile` 中 ``INPUT`` 语句列出的所有头文件进行更新。
|
||||
|
||||
3. ``INPUT`` 语句的每一行（以 ``##`` 开头的注释除外）都包含一个到头文件 ``*.h`` 的路径，用于生成相应的 ``*.inc`` 文件::
|
||||
|
||||
##
|
||||
## Wi-Fi - API Reference
|
||||
##
|
||||
../components/esp32/include/esp_wifi.h \
|
||||
../components/esp32/include/esp_smartconfig.h \
|
||||
|
||||
4. 头文件被展开时， ``sdkconfig.h`` 中默认定义的宏以及在 SOC 特定 ``include/soc/*_caps.h`` 头文件中定义的宏都会被展开。这样，头文件就可以根据 ``IDF_TARGET`` 的值来添加或排除相关内容。
|
||||
|
||||
5. ``*.inc`` 文件中包含每次文档构建时自动生成的 API 成员格式化参考。所有 ``*.inc`` 文件都位于 Sphinx 的 ``_build`` 路径下。如需查看生成指令，以 ``esp_wifi.h`` 为例，运行 ``python gen-dxd.py esp32/include/esp_wifi.h``。
|
||||
|
||||
6. 用以下语句在文档中显示 ``*.inc`` 文件的内容::
|
||||
|
||||
.. include-build-file:: inc/esp_wifi.inc
|
||||
|
||||
参考示例：:idf_file:`docs/en/api-reference/network/esp_wifi.rst`
|
||||
|
||||
7. 你也可以不用 ``*.inc`` 文件，而使用自己的方式描述 API。参考示例：:idf_file:`docs/en/api-reference/storage/fatfs.rst`。
|
||||
|
||||
以下为常见的 ``.. doxygen...::`` 指令：
|
||||
|
||||
* 函数 - ``.. doxygenfunction:: name_of_function``
|
||||
* 联合体 - ``.. doxygenunion:: name_of_union``
|
||||
* 结构体 - ``.. doxygenstruct:: name_of_structure`` 和 ``:members:``
|
||||
* 宏 - ``.. doxygendefine:: name_of_define``
|
||||
* 类定义 - ``.. doxygentypedef:: name_of_type``
|
||||
* 枚举 - ``.. doxygenenum:: name_of_enumeration``
|
||||
|
||||
如需更多信息，请参考 `Breathe 文档 <https://breathe.readthedocs.io/en/latest/directives.html>`_。
|
||||
|
||||
使用 `link custom role` 指令添加指向头文件的链接，如下所示::
|
||||
|
||||
* :component_file:`path_to/header_file.h`
|
||||
|
||||
8. 在任何情况下，要生成 API 参考文档，应该更新文件 :idf_file:`docs/doxygen/Doxyfile` 并将其中的路径更新为正在添加文档的 ``*.h`` 头文件的路径。
|
||||
|
||||
9. 更改提交并构建文档后，可以查看文档的渲染效果。如有需要，为相应的头文件 :doc:`纠正注释 <../contribute/documenting-code>`。
|
||||
@ -1 +1,53 @@
|
||||
.. include:: ../../en/third-party-tools/platformio.rst
|
||||
.. _platformio:
|
||||
|
||||
PlatformIO
|
||||
##########
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. image:: ../../_static/platformio-logo.png
|
||||
:target: https://platformio.org/?utm_source=docs.espressif.com
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
什么是 PlatformIO？
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`PlatformIO <https://platformio.org/?utm_source=docs.espressif.com>`__
|
||||
是一个跨平台的嵌入式开发环境，能直接支持 ESP-IDF。
|
||||
|
||||
由于 PlatformIO 对 ESP-IDF 的支持并非由 Espressif 团队维护，
|
||||
如果遇到 PlatformIO 相关的问题，请通过 `官方 PlatformIO 库 <https://github.com/platformio>`_ 联系其开发人员。
|
||||
|
||||
要了解关于 PlatformIO 生态系统及其理念的详细概述，请参考
|
||||
`官方 PlatformIO 文档 <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_。
|
||||
|
||||
安装
|
||||
~~~~~~~~~~~~
|
||||
|
||||
* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_ 是一个可在 Windows，macOS 和 Linux 平台上使用的嵌入式 C/C++ 开发工具集。
|
||||
* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_ 是一个命令行工具，包含多平台编译系统，平台和库管理器以及其他集成组件。它可以与各种代码开发环境一起使用，还可以集成云平台和网络服务。
|
||||
|
||||
配置
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
请参阅 `PlatformIO 官方的 ESP-IDF 配置指南 <https://docs.platformio.org/en/latest/frameworks/espidf.html?utm_source=docs.espressif.com#configuration>`_。
|
||||
|
||||
教程
|
||||
~~~~~~~~~
|
||||
|
||||
- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis <https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
|
||||
|
||||
项目示例
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
请参阅 `PlatformIO 官方文档 <https://docs.platformio.org/en/latest/frameworks/espidf.html?utm_source=docs.espressif.com#examples>`__ 中 ESP-IDF 相关内容。
|
||||
|
||||
更多内容
|
||||
~~~~~~~~~~
|
||||
|
||||
访问以下链接探索 PlatformIO 生态系统：
|
||||
|
||||
- 了解更多 `与其他 IDE 或文本编辑器集成 <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_ 的信息。
|
||||
- 从 `PlatformIO 社区 <https://community.platformio.org/?utm_source=docs.espressif.com>`__ 获取帮助。
|
||||
Loading…
Reference in New Issue
Block a user