docs: Add "Creating Examples" docs page, template example README

docs/TEMPLATE_EXAMPLE_README.md

@@ -0,0 +1,59 @@
+_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._
+
+# _Example Title_
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+_What is this example? What does it do?_
+
+_What features of ESP-IDF does it use?_
+
+_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 datasheet/TRM this information can be found._
+
+## How to use example
+
+### 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 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
+
+```
+make menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+* _If there is any menuconfig configuration that the user user must set for this example, mention this here._
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+
+(To exit the serial monitor, type ``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:_
+
+```
+Use this style for pasting the log.
+```
+
+_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)_
+
+_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._

docs/en/contribute/creating-examples.rst

@@ -0,0 +1,36 @@
+Creating Examples
+=================
+
+Each ESP-IDF example is a complete project that someone else can copy and adapt the code to solve their own problem. Examples should demonstrate ESP-IDF functionality, while keeping this purpose in mind.
+
+Structure
+---------
+
+- The ``main`` directory should contain a source file named ``(something)_example_main.c`` with the main functionality.
+- If the example has additional functionality, split it logically into separate C or C++ source files under ``main`` and place a corresponding header file in the same directory.
+- If the example has a lot of additional functionality, consider adding a ``components`` directory to the example project and make some example-specific components with library functionality. Only do this if the components are specific to the example, if they're generic or common functionality then they should be added to ESP-IDF itself.
+- The example should have a ``README.md`` file. Use the `template example README`_ and adapt it for your particular example.
+- Examples should have an ``example_test.py`` file for running an automated example test. If submitting a GitHub Pull Request which includes an example, it's OK not to include this file initially. The details can be discussed as part of the PR.
+
+General Guidelines
+------------------
+
+Example code should follow the :doc:`style-guide`.
+
+Checklist
+---------
+
+Checklist before submitting a new example:
+
+* Example project name (in ``Makefile`` and ``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 `template example README`_.
+* 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.)
+* All code in the example is well structured and commented.
+* Any unnecessary code (old debugging logs, commented-out code, etc.) is removed from the example.
+* Options in the example (like network names, addresses, etc) are not hard-coded. Use configuration items if possible, or otherwise declare macros or constants)
+* Configuration items are provided in a ``KConfig.projbuild`` file with a menu named "Example Configuration". See existing example projects to see how this is done.
+* All original example code has a license header saying it is "in the public domain / CC0", and a warranty disclaimer clause. Alternatively, the example is licensed under Apache License 2.0. See existing examples for headers to adapt from.
+* Any adapted or third party example code has the original license header on it. This code must be licensed compatible with Apache License 2.0.
+
+.. _template example README: :idf_file:`/doc/TEMPLATE_EXAMPLE_README.md`

docs/en/contribute/style-guide.rst

@@ -183,9 +183,23 @@ Documenting code
 
 Please see the guide here: :doc:`documenting-code`.
 
-Structure and naming
---------------------
+.. _style-guide-naming:
 
+Naming
+------
+
+- Any variable or function which is only used in a single source file should be declared ``static``.
+
+- Public names (non-static variables and functions) should be namespaced with a per-component or per-unit prefix, to avoid naming collisions. ie ``esp_vfs_register()`` or ``esp_console_run()``. Starting the prefix with ``esp_`` for Espressif-specific names is optional, but should be consistent with any other names in the same component.
+
+- Static variables should be prefixed with ``s_`` for easy identification. For example, ``static bool s_invert``.
+
+- Avoid unnecessary abbreviations (ie shortening ``data`` to ``dat``), unless the resulting name would otherwise be very long.
+
+Structure
+---------
+
+To be written.
 
 
 Language features

docs/zh_CN/contribute/creating-examples.rst

@@ -0,0 +1 @@
+.. include:: ../../en/contribute/creating-examples.rst