pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'docs/provide_CN_trans_for_template.rst_and_platformio.rst' into 'master'

Browse Source 
docs: Provide Chinese translation for template.rst and platformio.rst

Closes DOC-6002

See merge request espressif/esp-idf!25398
This commit is contained in:
Ren Pei Ying
2023-09-09 02:23:00 +08:00
parent 2557513fb5 e99b500b9d
commit 035d8f9d01
4 changed files with 182 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/template.rst
+15 -13
View File
@@ -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.