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

CONTRIBUTING.rst

@@ -25,6 +25,8 @@ Before sending us a Pull Request, please consider this list of points:
 
 * Are comments and documentation written in clear English, with no spelling or grammar errors?
 
+* Example contributions are also welcome. Please check the :doc:`creating-examples` guide for these.
+
 * If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
 
 * If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
@@ -51,5 +53,6 @@ Related Documents
 
     style-guide
     documenting-code
+    creating-examples
     ../api-reference/template
-    contributor-agreement
+    contributor-agreement

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

examples/README.md

@@ -1,16 +1,28 @@
 # Examples
 
-This directory contains a growing number of simple example projects for esp-idf. These are intended to show basic esp-idf functionality, and to provide you can use for your own projects.
+This directory contains a range of example ESP-IDF projects. These are intended to demonstrate parts of ESP-IDF functionality, and to provide code that you can copy and adapt into your own projects.
 
-# Using Examples
+# Example Layout
+
+The examples are grouped into subdirectories by category. Each category directory contains one or more example projects:
+
+* `bluetooth` contains Bluetooth (BLE & BT Classic) examples.
+* `ethernet` contains Ethernet examples.
+* `get-started` contains some very simple examples with minimal functionality.
+* `mesh` contains Wi-Fi Mesh examples.
+* `peripherals` contains examples showing driver functionality for the various onboard ESP32 peripherals.
+* `protocols` contains examples showing network protocol interactions.
+* `storage` contains examples showing data storage methods using SPI flash or external storage like the SD/MMC interface.
+* `system` contains examples which demonstrate some internal chip features, or debugging & development tools.
+* `wifi` contains examples of advanced Wi-Fi features. (For network protocol examples, see `protocols` instead.)
 
-Building examples is the same as building any other project:
+# Using Examples
 
-* Follow the setup instructions in the top-level esp-idf README.
+Building an example is the same as building any other project:
 
-* Set `IDF_PATH` environment variable to point to the path to the esp-idf top-level directory.
-* Change into the directory of the example you'd like to build.
-* `make menuconfig` to configure the example. Most examples require a simple WiFi SSID & password via this configuration.
+* Follow the Getting Started instructions which include building the "Hello World" example.
+* Change into the directory of the new example you'd like to build.
+* `make menuconfig` to configure the example. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use).
 * `make` to build the example.
 * Follow the printed instructions to flash, or run `make flash`.
 
@@ -18,7 +30,7 @@ Building examples is the same as building any other project:
 
 Each example is a standalone project. The examples *do not have to be inside the esp-idf directory*. You can copy an example directory to anywhere on your computer in order to make a copy that you can modify and work with.
 
-The `IDF_PATH` environment variable is the only thing that connects the example to the rest of the `esp-idf` system.
+The `IDF_PATH` environment variable is the only thing that connects the example to the rest of ESP-IDF.
 
 If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template).
 
@@ -26,13 +38,4 @@ If you're looking for a more bare-bones project to start from, try [esp-idf-temp
 
 If you have a new example you think we'd like, please consider sending it to us as a Pull Request.
 
-Please read the esp-idf CONTRIBUTING.rst file which lays out general contribution rules.
-
-In addition, here are some tips for creating good examples:
-
-* A good example is documented and the basic options can be configured.
-* A good example does not contain a lot of code. If there is a lot of generic code in the example, consider refactoring that code into a standalone component and then use the component's API in your example.
-* Names (of files, functions, variables, etc.) inside examples should be distinguishable from names of other parts of IDF (ideally, use `example` in names.)
-* Functions and variables used inside examples should be declared static where possible.
-* Examples should demonstrate one distinct thing each. Avoid multi-purposed "demo" examples, split these into multiple examples instead.
-* Examples must be licensed under the Apache License 2.0 or (preferably for examples) if possible you can declare the example to be Public Domain / Creative Commons Zero.
+In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example.