Merge branch 'docs/update_example_readme_template' into 'master'

docs: Update ESP Timer example README

See merge request espressif/esp-idf!29844

docs/README.md

@@ -11,8 +11,20 @@ Use actual documentation generated within about 20 minutes on each commit:
 * English: https://docs.espressif.com/projects/esp-idf/en/latest/
 * 中文: https://docs.espressif.com/projects/esp-idf/zh_CN/latest/
 
-The above URLs are all for the master branch latest version. Click the drop-down in the bottom left to choose a stable version or to download a PDF.
+After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the correct Espressif chip (target) and ESP-IDF version selected in the dropdown menus. You can also find a link on the bottom right to download the PDF version.
 
 # Building Documentation
 
-The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md
+The documentation is built using the python package `esp-docs`, which can be installed by running:
+
+```
+pip install esp-docs
+```
+
+For a summary of available options, run:
+
+```
+build-docs --help
+```
+
+For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md

docs/TEMPLATE_EXAMPLE_README.md

@@ -1,67 +1,138 @@
-_Note that this is a template for an ESP-IDF example README.md file. When using this template, replace all these emphasised placeholders with example-specific content._
+_Note that this is a template for an ESP-IDF example README.md file. When using this template, replace all the emphasized placeholders (in italics) with example-specific content._
 
-| Supported Targets | _Supported target, e.g. ESP32_ | _Another supported target, e.g. ESP32-S3_ |
-| ----------------- | ------------------------------ | ----------------------------------------- |
+_For your reference and inspiration, the application README already following this template is [ESP Timer Example](../examples/system/esp_timer/README.md)._
+
+_While creating your example, use this template in conjunction with the guidelines given in [Creating Examples](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/creating-examples.html)._
+
+| Supported Targets | _ESP32_ | _ESP32-XX_ |
+| ----------------- | ------- | ---------- |
 
-_If the example supports all targets supported by ESP-IDF then the table can be omitted_
 # _Example Title_
 
-(See the README.md file in the upper level 'examples' directory for more information about examples.)
+_Example Title should use the word "example" instead of "demo", "test" or any similar words._
+
+(For general overview of examples and their usage, see the `README.md` file in the upper level 'examples' directory.)
+
+> **Note**:
+>
+> After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the appropriate **Espressif chip** (target) and **ESP-IDF version** selected in the dropdown menus.
 
 _What is this example? What does it do?_
 
-_What features of ESP-IDF does it use?_
+_What feature(s) of ESP-IDF does this example use? Briefly introduce them and give a link to the API reference(s)._
+
+_What could someone create based on this example? Think of applications, use cases, etc._
 
-_What could someone create based on this example? ie applications/use cases/etc_
+_If there are any acronyms or Espressif-only words used here, explain them or mention where in the hardware or software documentation this information can be found._
 
-_If there are any acronyms or Espressif-only words used here, explain them or mention where in the datasheet/TRM this information can be found._
 
-## How to use example
+## Usage
+
+The subsections below give only absolutely necessary information. For full steps to configure ESP-IDF and use it to build and run projects, see [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started).
+
 
 ### Hardware Required
 
-_If possible, example should be able to run on any commonly available ESP32 development board. Otherwise, describe what specific hardware should be used._
+_If possible, the example should be able to run on any commonly available development board based on a chip listed in the Supported Targets table. Otherwise, describe what specific hardware should be used._
+
+_For beginner-friendly examples, provide a more detailed list of the required hardware. For more advanced examples, omit self-evident information._
+
+_If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include the links if applicable. Explain how to set them up._
+
+_For examples where a chip is connected to some other hardware, include a table or schematics with connection details._
 
-_If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include links if applicable. Explain how to set them up._
 
-### Configure the project
+### Software Required _(optional)_
+
+_If any additional software is needed, mention it here and include the links. Mention the software version required if applicable. Explain how to set it up._
+
+
+### Set Chip Target
+
+First of all, your target must be supported by both:
+
+- **By your ESP-IDF version**: For the full list of supported targets, run:
+  ```
+  idf.py --list-targets
+  ```
+- **By this example**: For the full list of supported targets,  refer to the supported targets table at the top of this README.
+
+After you make sure that your target is supported, go to your example project directory and [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
+
+```
+idf.py set-target <target>
+```
+
+For example, to set esp32 as the chip target, run:
+
+```
+idf.py set-target esp32
+```
+
+
+### Configure the Project
+
+_Set the required Kconfig options differing from the ESP-IDF defaults in [sdkconfig.defaults](./sdkconfig.defaults) and add comments there on WHY these options are needed. (Remember, WHAT these options do is already documented in the Project Configuration document, so no need to repeat this information.)_
+
+_If the required Kconfig options are pre-set in `sdkconfig.defaults`, add the following sentences as a separate paragraph: This example does not need configuration. The required Kconfig options differing from the ESP-IDF defaults are pre-set for this particular example in [sdkconfig.defaults](./sdkconfig.defaults)._
+
+For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) > _Name of relevant section(s)_.
+
+To conveniently check or modify Kconfig options for this example in a project configuration menu, run:
 
 ```
 idf.py menuconfig
 ```
 
-* _If there is any project configuration that the user must set for this example, mention this here._
+_If there is anything else that the user must configure for this example to work, mention it here._
+
 
 ### Build and Flash
 
-Build the project and flash it to the board, then run monitor tool to view serial output:
+Execute the following command to build the project, flash it to your development board, and run the monitor tool to view the serial output:
 
 ```
-idf.py -p PORT flash monitor
+idf.py build flash monitor
 ```
 
-(Replace PORT with the name of the serial port to use.)
+This command can be reduced to `idf.py flash monitor`.
 
-(To exit the serial monitor, type ``Ctrl-]``.)
+If the above command fails, check the log on the serial monitor which usually provides information on the possible cause of the issue.
+
+To exit the serial monitor, use `Ctrl` + `]`.
 
-See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
 
 ## Example Output
 
-_Include an example of the console output from the running example, here:_
+_For different reasons, an example's console output might not be informative enough for the user to realize that something went wrong. To allow users to check that the example is running correctly on their side, be sure to include here the expected console output as given below._
+
+If you see the following console output, your example should be running correctly:
 
 ```
-Use this style for pasting the log.
+Paste console output as a code snippet like this
 ```
 
-_If the user is supposed to interact with the example at this point (read/write GATT attribute, send HTTP request, press button, etc. then mention it here)_
+_If the user is supposed to interact with the example at this point, mention it here (read/write GATT attribute, send HTTP request, press button, etc.)_
+
+
+## Example Breakdown _(optional)_
+
+_If the example source code is lengthy, complex, or cannot be easily understood, use this section to break down and explain the source code. This can be done by breaking down the execution path step by step, or explaining what each major function/task/source file does. Add sub titles if necessary. Remove this section for very simple examples where the source code is self explanatory._
 
-_For examples where ESP32 is connected  with some other hardware, include a table or schematics with connection details._
 
 ## Troubleshooting
 
-_If there are any likely problems or errors which many users might encounter, mention them here. Remove this section for very simple examples where nothing is likely to go wrong._
+_Remove this section for very simple examples where nothing is likely to go wrong._
+
+_There might be typical issues or errors that the user is likely to encounter while working with this example. If the issue is related to the ESP-IDF feature in general, mention it in Troubleshooting of this feature's API reference. If the issue is related to this example only, mention such issue here._
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub.
+
+
+## Reference
 
-## Example Breakdown
+_Provide references to important documents_
 
-_If the example source code is lengthy, complex, or cannot be easily understood, use this section to break down and explain the source code. This can be done by breaking down the execution path step by step, or explaining what each major function/task/source file does. Add sub titles if necessary. Remove this section for very simple examples where the source code is self explanatory._
+- Link to the ESP-IDF feature's API reference, for example [ESP-IDF: ESP Timer feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html)
+- [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started)
+- [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) (Kconfig Options)

docs/en/contribute/creating-examples.rst

@@ -24,7 +24,6 @@ Checklist
 
 Checklist before submitting a new example:
 
-* Example project name (in ``README.md``) uses the word "example". Use "example" instead of "demo", "test" or similar words.
 * Example does one distinct thing. If the example does more than one thing at a time, split it into two or more examples.
 * Example has a ``README.md`` file which is similar to the :idf_file:`template example README <docs/TEMPLATE_EXAMPLE_README.md>`.
 * Functions and variables in the example are named according to :ref:`naming section of the style guide <style-guide-naming>`. For non-static names which are only specific to the example's source files, you can use ``example`` or something similar as a prefix.

docs/zh_CN/contribute/creating-examples.rst

@@ -24,7 +24,6 @@
 
 提交一个新的示例项目之前，需要检查以下内容：
 
--  示例项目的名字（包括 ``README.md`` 中）应使用 ``example``，而不要写 “demo”，“test” 等词汇。
 -  每个示例项目只能有一个主要功能。如果某个示例项目有多个主要功能，请将其拆分为两个或更多示例项目。
 -  每个示例项目应包含一个 ``README.md`` 文件，建议使用 :idf_file:`示例项目 README 模板 <docs/TEMPLATE_EXAMPLE_README.md>`。
 -  示例项目中的函数和变量的命令要遵循 :ref:`命名规范 <style-guide-naming>` 中的要求。对于仅在示例项目源文件中使用的非静态变量/函数，请使用 ``example`` 或其他类似的前缀。

examples/README.md

@@ -31,15 +31,56 @@ In addition to these examples, `commmon_components` directory contains code shar
 
 ## Using Examples
 
-Before building an example, be sure to follow the [ESP-IDF Getting Started Guide](https://idf.espressif.com/) to ensure you have the required development environment.
+Before building an example, follow the [ESP-IDF Getting Started](https://idf.espressif.com/) to ensure you have the required development environment.
 
-Building an example is the same as building any other project:
+### Set Chip Target
+
+First of all, your target must be supported by both:
+
+- **By your ESP-IDF version**: For the full list of supported targets, run:
+  ```
+  idf.py --list-targets
+  ```
+- **By this example**: For the full list of supported targets,  refer to the supported targets table at the top of this README.
+
+After you make sure that your target is supported, go to your example project directory and [set the chip target](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-py.html#select-the-target-chip-set-target):
+
+```
+idf.py set-target <target>
+```
+
+For example, to set esp32 as the chip target, run:
+
+```
+idf.py set-target esp32
+```
+
+
+### Configure the Project
+
+For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) > ESP Timer (High Resolution Timer).
+
+To conveniently check or modify Kconfig options for this example in a project configuration menu, run:
+
+```
+idf.py menuconfig
+```
+
+
+### Build and Flash
+
+Execute the following command to build the project, flash it to your development board, and run the monitor tool to view the serial output:
+
+```
+idf.py build flash monitor
+```
+
+This command can be reduced to `idf.py flash monitor`.
+
+If the above command fails, check the log on the serial monitor which usually provides information on the possible cause of the issue.
+
+To exit the serial monitor, use `Ctrl` + `]`.
 
-- Change into the directory of the new example you'd like to build.
-- Run `idf.py set-target TARGET` to select the correct chip target to build before opening the project configuration menu. By default the target is `esp32`. For all options see `idf.py set-target --help`
-- Run `idf.py menuconfig` to open the project configuration menu. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use).
-- `idf.py build` to build the example.
-- Follow the printed instructions to flash, or run `idf.py -p PORT flash`.
 
 ## Running Test Python Script (pytest)