docs: introduce new rules for writing documents

docs/en/contribute/documenting-code.rst

@@ -42,7 +42,7 @@ Go for it!
 
 When writing code for this repository, please follow guidelines below.
 
-1. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information on purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
+1. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information about purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
 
 2. Documentation of function should describe what this function does. If it accepts input parameters and returns some value, all of them should be explained.
 
@@ -75,14 +75,16 @@ When writing code for this repository, please follow guidelines below.
     *    - other error codes from the underlying storage driver
     *
 
-7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``.
+7. Overview of functionality of documented header file, or group of files that make a library, should be placed in a separate ``README.rst`` file of the same directory. If this directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``.
 
 
 Go one extra mile
 -----------------
 
-There is couple of tips, how you can make your documentation even better and more useful to the reader.
+Here are a couple of tips on how you can make your documentation even better and more useful to the reader and writer.
 
+When writing codes, please follow the guidelines below: 
+ 
 1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. ::
 
     *
@@ -133,7 +135,37 @@ There is couple of tips, how you can make your documentation even better and mor
 
     Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
 
-6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory.
+6. Prepare one or more complete code examples together with description. Place description to a separate file ``README.md`` in specific folder of :idf:`examples` directory.
+
+Standardize Document Format
+-------------------------------
+
+When it comes to text, please follow guidelines below to provide well formatted Markdown (.md) or reST (.rst) documents.
+
+1. Please ensure that one paragraph is written in one line. Don't break lines like below. Breaking lines to enhance readability is only suitable for writing codes. To make the text easier to read, it is recommended to place an empty line to separate the paragraph.
+
+    .. figure:: ../../_static/doc-format1-recommend.png
+        :align: center
+        :scale: 30%
+        :alt: One line for one paragraph - recommend (click to enlarge)
+
+        One line for one paragraph (click to enlarge)
+
+    .. figure:: ../../_static/doc-format2-notrecommend.png
+        :align: center
+        :scale: 30%
+        :alt: One line for one paragraph - not recommend (click to enlarge)
+
+        No line breaks within the same paragraph (click to enlarge)
+
+2. Please make the line number of CN and EN documents consistent like below. The benefit of this approach is that it can save time for both writers and translators. When non-bilingual writers need to update text, they only need to update the same line in the corresponding CN or EN document. For translators, if documents are updated in English, then translators can quickly locate where to update in the corresponding CN document later. Besides, by comparing the total number of lines in EN and CN documents, you can quickly find out whether the CN version lags behind the EN version.
+
+    .. figure:: ../../_static/doc-format3-recommend.png
+        :align: center
+        :scale: 50%
+        :alt: Keep the line number for EN and CN files consistent (click to enlarge)
+        
+        Keep the line number for EN and CN documents consistent (click to enlarge)
 
 .. _link-custom-roles:
 
@@ -515,7 +547,7 @@ Note that this is a feature intended to simply testing and debugging during writ
 
 Fast build
 """"""""""
-Another trick to speed up building is to skip including doxygen generated API documention into the Sphinx build process, skipping this drastically reduces build times.
+Another trick to speed up building is to skip including doxygen generated API documention into the Sphinx build process, skipping this drastically reduces build time.
 
 This can be achieved by adding the fast-build argument::
 

docs/zh_CN/contribute/documenting-code.rst

@@ -83,6 +83,8 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵
 
 以下小贴士可以帮助你进一步提高文档质量，增强可读性。
 
+对于代码，请遵循下列准则：
+
 1. 添加代码片段举例说明。请在片段前后添加 ``@code{c}`` 和 ``@endcode`` 命令。 ::
 
     *
@@ -135,6 +137,36 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵
 
 6. 准备一个或更多完整的代码示例和描述，将描述放入单独的 ``README.md`` 文件中，置于 :idf:`examples` 目录的特定文件夹中。
 
+统一文档格式
+------------------
+
+对于 Markdown (.md) 或 reST (.rst) 文档中的文本类信息，请遵守下列规范保证文档格式统一。
+
+1. 请确保一个段落仅有一行，同段落中不用断行，如下图所示。通过断行来提高可读性的准则仅限用于书写代码。对于文本类信息，可以通过添加空白行来增加段落，从而提高可读性。
+
+    .. figure:: ../../_static/doc-format1-recommend.png
+        :align: center
+        :scale: 30%
+        :alt: 推荐一个段落仅有一行（点击放大）
+
+        一个段落仅有一行（点击放大）
+
+    .. figure:: ../../_static/doc-format2-notrecommend.png
+        :align: center
+        :scale: 30%
+        :alt: 不推荐段落内断行（点击放大）
+
+        不推荐段落内断行（点击放大）
+
+2. 请确保中文与英文文档中的行号一一对应，如下图所示。这个方法可以提高日后更新文档的效率。当工程师需要更新文档时，可以迅速定位到对应中文或英文文档的同一行进行更新。对于翻译人员来说，如果文档仅更新了英文版本，译员可以在对应的中文版本中迅速找到需要更新的地方。此外，通过比较中英文文档中的总行数，可以快速判断中文文档是否进行了及时更新。
+
+    .. figure:: ../../_static/doc-format3-recommend.png
+        :align: center
+        :scale: 50%
+        :alt: 中英文文档中行号一一对应（点击放大）
+
+        中英文文档行号一一对应（点击放大）
+
 .. _link-custom-roles:
 
 链接到示例
@@ -513,6 +545,16 @@ Doxygen 的安装取决于操作系统：
 
 请注意，这一功能仅用于文档写作过程中的检查和测试。其生成的 HTML 页面并非渲染完成后的格式，比如，运行这一指令并不会生成一个列有所有文档的索引，而且如果其中涉及到任何还未生成的文档参考都将导致错误警报出现。
 
+快速生成文档
+""""""""""""""""
+可以通过跳过 doxygen 生成的 API 文档直接进入 Sphinx 构建过程来加速文档生成，这样做可以大幅缩短文档构建时间。
+
+可通过添加如下参数来实现::
+
+    ./build_docs.py build -f
+
+或者通过设置环境变量 `DOCS_FAST_BUILD`。请注意 `-f` 参数是 `build` 的一个子参数，因此必须放在 `build` 后面。
+
 生成 PDF
 """"""""""""